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

package/dist/workflows/dag/project-governance-context.js

@@ -0,0 +1,514 @@
+import { createHash } from "node:crypto";
+import { open, readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { writeTextAtomic } from "../../infrastructure/harness/atomic-write.js";
+/**
+ * Project Governance Context resolver.
+ *
+ * Deterministic, repository-local resolution of the applicable `AGENTS.md`
+ * chain (root -> nearest) and its explicit code-standard references, scoped to
+ * the actual writer changeset of the current DAG run. No model search; no
+ * repository writes; never reads outside the repository.
+ *
+ * Mirrors the proven shape of skill-snapshot.ts: run-owned, schemaVersion,
+ * resolverVersion, sha256, cycle-safe, path-contained, bounded, auditable.
+ */
+export const PROJECT_GOVERNANCE_CONTEXT_SCHEMA_VERSION = 1;
+export const PROJECT_GOVERNANCE_CONTEXT_RESOLVER_VERSION = 1;
+export const PROJECT_GOVERNANCE_CONTEXT_REL_PATH = ".runtime/project-governance-context.json";
+export const AGENTS_MD_FILENAME = "AGENTS.md";
+const DAG_RUNS_PREFIX = ".harness/dag-runs/";
+const MAX_AGENTS_MD_BYTES = 256 * 1024;
+const MAX_STANDARD_BYTES = 256 * 1024;
+const MAX_REFERENCED_STANDARDS = 32;
+const MAX_GOVERNANCE_DISCOVERY_DIRECTORIES = 10_000;
+const GOVERNANCE_DISCOVERY_IGNORED_DIRECTORIES = new Set([
+    ".git",
+    ".codegraph",
+    ".harness",
+    ".worktrees",
+    "node_modules",
+    "dist",
+    "build",
+]);
+const STANDARD_MARKER_RE = /<!--\s*standard:\s*([^\s>]+)\s*-->/gi;
+const GOVERNANCE_REFERENCE_LINE_RE = /(?:代码|编码|开发|工程|测试|验证|架构|治理|规范|标准|约束|要求|原则|流程|code|coding|development|engineering|test|verification|architecture|governance|standard|style|convention|guideline|principle|workflow|requirement)/i;
+const ADVISORY_REFERENCE_LINE_RE = /(?:可选|建议|参考|advisory|optional|recommend(?:ed|ation)?|for reference)/i;
+const MARKDOWN_LINK_RE = /\[[^\]]*\]\(([^)\s]+)(?:\s+["'][^"']*["'])?\)/g;
+const INLINE_MARKDOWN_PATH_RE = /`((?:\.?\.?[\\/])?[A-Za-z0-9_.@/\\-]+\.md(?:#[A-Za-z0-9_.-]+)?)`/gi;
+const AT_MARKDOWN_PATH_RE = /(?:^|\s)@([^\s<>]+\.md(?:#[^\s<>]+)?)/gi;
+export class DagProjectGovernanceIntegrityError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "DagProjectGovernanceIntegrityError";
+    }
+}
+/**
+ * Cheap generation-time capability probe. Runtime applicability is still
+ * resolved from the writer changeset; this probe only prevents governance
+ * fields/gates from changing DAGs for repositories that have no AGENTS.md at
+ * all. Heavy generated/runtime directories are intentionally excluded.
+ */
+export async function discoverProjectGovernancePresence(repoRoot) {
+    const queue = [path.resolve(repoRoot)];
+    let visited = 0;
+    while (queue.length > 0 && visited < MAX_GOVERNANCE_DISCOVERY_DIRECTORIES) {
+        const directory = queue.shift();
+        visited += 1;
+        let entries;
+        try {
+            entries = await readdir(directory, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        if (entries.some((entry) => entry.isFile() && entry.name === AGENTS_MD_FILENAME)) {
+            return true;
+        }
+        for (const entry of entries) {
+            if (entry.isDirectory() &&
+                !entry.isSymbolicLink() &&
+                !GOVERNANCE_DISCOVERY_IGNORED_DIRECTORIES.has(entry.name)) {
+                queue.push(path.join(directory, entry.name));
+            }
+        }
+    }
+    return false;
+}
+function sha256(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+function toPosix(p) {
+    return p.replace(/\\/g, "/");
+}
+function normalizeRelPath(value) {
+    return toPosix(value).replace(/^\.\//, "");
+}
+function isWithinRepo(repoRoot, candidateAbs) {
+    const rel = path.relative(repoRoot, candidateAbs);
+    if (!rel)
+        return false; // equal to root
+    // On POSIX and Windows alike, an escaping relative path starts with ".."
+    // or is absolute on a different drive (path.relative yields an absolute path).
+    return !rel.startsWith("..") && !path.isAbsolute(toPosix(rel));
+}
+/**
+ * Walk from the changed file's directory up to repo root, returning the list of
+ * ancestor directories (root -> ... -> file's dir) that could contain an
+ * AGENTS.md. The file's own directory is included; repo root is included.
+ */
+function ancestorDirectories(repoRoot, fileRel) {
+    const fileAbs = path.resolve(repoRoot, normalizeRelPath(fileRel));
+    const fileDirAbs = path.dirname(fileAbs);
+    const dirs = [];
+    let current = fileDirAbs;
+    for (;;) {
+        dirs.push(current);
+        const parent = path.dirname(current);
+        if (parent === current)
+            break; // filesystem root
+        if (path.relative(repoRoot, current) === "")
+            break; // reached repo root
+        current = parent;
+    }
+    // dirs are fileDir -> ... -> repoRoot; reverse to root -> ... -> nearest
+    return dirs.reverse().filter((dir) => {
+        const rel = path.relative(repoRoot, dir);
+        return !rel.startsWith("..") && !path.isAbsolute(toPosix(rel));
+    });
+}
+function directoryRel(repoRoot, dirAbs) {
+    const rel = path.relative(repoRoot, dirAbs);
+    return normalizeRelPath(rel);
+}
+async function readBounded(fileAbs, maxBytes) {
+    const handle = await open(fileAbs, "r");
+    try {
+        const info = await handle.stat();
+        if (!info.isFile()) {
+            const error = new Error(`governance reference is not a regular file: ${fileAbs}`);
+            error.code = "EINVAL";
+            throw error;
+        }
+        if (info.size > maxBytes) {
+            const error = new Error(`governance file exceeds ${maxBytes} byte limit: ${fileAbs} (${info.size} bytes)`);
+            error.code = "EFBIG";
+            throw error;
+        }
+        const buffer = await handle.readFile();
+        if (buffer.length > maxBytes) {
+            const error = new Error(`governance file grew beyond ${maxBytes} byte limit while reading: ${fileAbs}`);
+            error.code = "EFBIG";
+            throw error;
+        }
+        return {
+            content: buffer.toString("utf-8"),
+            bytes: buffer.length,
+            sha256: sha256(buffer),
+        };
+    }
+    finally {
+        await handle.close();
+    }
+}
+function normalizeDeclaredReferenceToken(token) {
+    return token
+        .trim()
+        .replace(/^<|>$/g, "")
+        .split("#", 1)[0]
+        .split("?", 1)[0];
+}
+/**
+ * Resolve both the explicit marker grammar and ordinary AGENTS.md indexes:
+ * Markdown links, backtick paths, and @path references are accepted only on
+ * lines that clearly describe governance/engineering requirements. This keeps
+ * traversal bounded while supporting normal project documentation maps.
+ */
+function parseStandardReferences(content) {
+    const out = [];
+    const seen = new Set();
+    const push = (token, enforcement) => {
+        const normalized = normalizeDeclaredReferenceToken(token);
+        if (!normalized || seen.has(normalized))
+            return;
+        seen.add(normalized);
+        out.push({ path: normalized, enforcement });
+    };
+    let match;
+    STANDARD_MARKER_RE.lastIndex = 0;
+    while ((match = STANDARD_MARKER_RE.exec(content)) !== null) {
+        const token = match[1].trim();
+        if (token)
+            push(token, "mandatory");
+    }
+    for (const line of content.split(/\r?\n/)) {
+        if (!GOVERNANCE_REFERENCE_LINE_RE.test(line))
+            continue;
+        const enforcement = ADVISORY_REFERENCE_LINE_RE.test(line)
+            ? "advisory"
+            : "mandatory";
+        for (const pattern of [MARKDOWN_LINK_RE, INLINE_MARKDOWN_PATH_RE, AT_MARKDOWN_PATH_RE]) {
+            pattern.lastIndex = 0;
+            while ((match = pattern.exec(line)) !== null) {
+                push(match[1], enforcement);
+            }
+        }
+    }
+    return out;
+}
+function isHarnessRunPath(fileRel) {
+    const normalized = normalizeRelPath(fileRel);
+    return normalized.startsWith(DAG_RUNS_PREFIX);
+}
+export async function buildProjectGovernanceContext(input) {
+    const repoRoot = path.resolve(input.cwd);
+    const now = (input.now ?? new Date()).toISOString();
+    // Aggregate changed files, excluding .harness/dag-runs/** (run-owned).
+    const allChanged = Array.from(new Set(input.changeManifest
+        .flatMap((entry) => entry.changedFiles)
+        .map((f) => normalizeRelPath(f))
+        .filter((f) => f.length > 0 && !isHarnessRunPath(f)))).sort();
+    if (allChanged.length === 0) {
+        return {
+            schemaVersion: PROJECT_GOVERNANCE_CONTEXT_SCHEMA_VERSION,
+            resolverVersion: PROJECT_GOVERNANCE_CONTEXT_RESOLVER_VERSION,
+            runId: input.runId,
+            createdAt: now,
+            applicable: false,
+            changeManifest: input.changeManifest,
+            agentsMdChain: [],
+            referencedStandards: [],
+            unresolvedReferences: [],
+            diagnostics: [],
+        };
+    }
+    // Collect candidate AGENTS.md directories: for each changed file, walk
+    // root -> nearest. Deduplicate by directory; do NOT scan unrelated dirs.
+    const dirToApplies = new Map();
+    for (const fileRel of allChanged) {
+        for (const dirAbs of ancestorDirectories(repoRoot, fileRel)) {
+            const dirRel = directoryRel(repoRoot, dirAbs);
+            let bucket = dirToApplies.get(dirRel);
+            if (!bucket) {
+                bucket = new Set();
+                dirToApplies.set(dirRel, bucket);
+            }
+            bucket.add(fileRel);
+        }
+    }
+    // Order directories root -> nearest (shortest rel path first, then lex).
+    const orderedDirs = [...dirToApplies.entries()].sort((a, b) => {
+        if (a[0].length !== b[0].length)
+            return a[0].length - b[0].length;
+        return a[0].localeCompare(b[0]);
+    });
+    const agentsMdChain = [];
+    for (const [dirRel, appliesSet] of orderedDirs) {
+        const dirAbs = path.join(repoRoot, dirRel);
+        const agentsPath = path.join(dirAbs, AGENTS_MD_FILENAME);
+        let bytes;
+        let contentSha256;
+        try {
+            const read = await readBounded(agentsPath, MAX_AGENTS_MD_BYTES);
+            bytes = read.bytes;
+            contentSha256 = read.sha256;
+        }
+        catch (error) {
+            const code = error && typeof error === "object" && "code" in error
+                ? error.code
+                : undefined;
+            if (code === "ENOENT") {
+                // No AGENTS.md in this directory; skip without error (bounded, no scan).
+                continue;
+            }
+            throw new DagProjectGovernanceIntegrityError(`failed to read applicable AGENTS.md at ${normalizeRelPath(path.relative(repoRoot, agentsPath))}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+        const fileRel = dirRel === "" ? AGENTS_MD_FILENAME : `${dirRel}/${AGENTS_MD_FILENAME}`;
+        agentsMdChain.push({
+            directory: dirRel,
+            path: fileRel,
+            sha256: contentSha256,
+            bytes,
+            appliesTo: [...appliesSet].sort(),
+        });
+    }
+    const referencedStandards = [];
+    const unresolvedReferences = [];
+    const resolvedPaths = new Set();
+    const diagnostics = [];
+    for (const [entry, entryIndex] of agentsMdChain.map((e, i) => [e, i])) {
+        const dirAbs = path.join(repoRoot, entry.directory);
+        let content;
+        try {
+            const read = await readBounded(path.join(dirAbs, AGENTS_MD_FILENAME), MAX_AGENTS_MD_BYTES);
+            content = read.content;
+        }
+        catch {
+            // Already proven to exist above; treat as read error defensively.
+            diagnostics.push(`failed to re-read AGENTS.md at ${entry.path} for reference parsing`);
+            continue;
+        }
+        const refs = parseStandardReferences(content);
+        for (const ref of refs) {
+            if (referencedStandards.length + unresolvedReferences.length >= MAX_REFERENCED_STANDARDS) {
+                diagnostics.push(`governance reference budget reached at ${MAX_REFERENCED_STANDARDS}; remaining references ignored`);
+                break;
+            }
+            const declaredPath = normalizeRelPath(ref.path);
+            if (path.isAbsolute(toPosix(ref.path)) ||
+                path.win32.isAbsolute(ref.path) ||
+                declaredPath.split("/").includes("..") ||
+                /^[a-z][a-z0-9+.-]*:/i.test(ref.path)) {
+                unresolvedReferences.push({
+                    fromAgentsMd: entryIndex,
+                    declaredPath: ref.path,
+                    reason: "out-of-repo",
+                });
+                continue;
+            }
+            // Standard references are repo-root-relative (project convention for
+            // AGENTS.md), not relative to the AGENTS.md's own directory.
+            const candidateAbs = path.resolve(repoRoot, declaredPath);
+            if (!isWithinRepo(repoRoot, candidateAbs)) {
+                unresolvedReferences.push({
+                    fromAgentsMd: entryIndex,
+                    declaredPath: ref.path,
+                    reason: "out-of-repo",
+                });
+                continue;
+            }
+            const candidateRel = normalizeRelPath(path.relative(repoRoot, candidateAbs));
+            if (resolvedPaths.has(candidateRel)) {
+                unresolvedReferences.push({
+                    fromAgentsMd: entryIndex,
+                    declaredPath: ref.path,
+                    reason: "cycle",
+                });
+                continue;
+            }
+            try {
+                const read = await readBounded(candidateAbs, MAX_STANDARD_BYTES);
+                resolvedPaths.add(candidateRel);
+                referencedStandards.push({
+                    fromAgentsMd: entryIndex,
+                    path: candidateRel,
+                    sha256: read.sha256,
+                    bytes: read.bytes,
+                    scope: declaredPath,
+                    enforcement: ref.enforcement,
+                });
+            }
+            catch (error) {
+                const code = error && typeof error === "object" && "code" in error
+                    ? error.code
+                    : undefined;
+                unresolvedReferences.push({
+                    fromAgentsMd: entryIndex,
+                    declaredPath: ref.path,
+                    reason: code === "ENOENT" ? "missing" : "read-error",
+                });
+            }
+        }
+    }
+    const applicable = agentsMdChain.length > 0;
+    return {
+        schemaVersion: PROJECT_GOVERNANCE_CONTEXT_SCHEMA_VERSION,
+        resolverVersion: PROJECT_GOVERNANCE_CONTEXT_RESOLVER_VERSION,
+        runId: input.runId,
+        createdAt: now,
+        applicable,
+        changeManifest: input.changeManifest,
+        agentsMdChain,
+        referencedStandards,
+        unresolvedReferences,
+        diagnostics,
+    };
+}
+function serializeContext(ctx) {
+    return `${JSON.stringify(ctx, null, 2)}\n`;
+}
+const agentsMdEntrySchema = z.object({
+    directory: z.string(),
+    path: z.string().min(1),
+    sha256: z.string().regex(/^[a-f0-9]{64}$/),
+    bytes: z.number().int().nonnegative(),
+    appliesTo: z.array(z.string()),
+}).strict();
+const resolvedStandardSchema = z.object({
+    fromAgentsMd: z.number().int().nonnegative(),
+    path: z.string().min(1),
+    sha256: z.string().regex(/^[a-f0-9]{64}$/),
+    bytes: z.number().int().nonnegative(),
+    scope: z.string().min(1),
+    enforcement: z.enum(["mandatory", "advisory"]),
+}).strict();
+const unresolvedReferenceSchema = z.object({
+    fromAgentsMd: z.number().int().nonnegative(),
+    declaredPath: z.string().min(1),
+    reason: z.enum(["out-of-repo", "missing", "cycle", "invalid", "read-error"]),
+}).strict();
+const changeManifestSchema = z.object({
+    writerNodeId: z.string().min(1),
+    changedFiles: z.array(z.string()),
+}).strict();
+const projectGovernanceContextSchema = z.object({
+    schemaVersion: z.literal(PROJECT_GOVERNANCE_CONTEXT_SCHEMA_VERSION),
+    resolverVersion: z.literal(PROJECT_GOVERNANCE_CONTEXT_RESOLVER_VERSION),
+    runId: z.string().min(1),
+    createdAt: z.string().datetime(),
+    applicable: z.boolean(),
+    changeManifest: z.array(changeManifestSchema),
+    agentsMdChain: z.array(agentsMdEntrySchema),
+    referencedStandards: z.array(resolvedStandardSchema),
+    unresolvedReferences: z.array(unresolvedReferenceSchema),
+    diagnostics: z.array(z.string()),
+}).strict();
+const projectGovernanceContextRefSchema = z.object({
+    schemaVersion: z.literal(PROJECT_GOVERNANCE_CONTEXT_SCHEMA_VERSION),
+    resolverVersion: z.literal(PROJECT_GOVERNANCE_CONTEXT_RESOLVER_VERSION),
+    path: z.literal(PROJECT_GOVERNANCE_CONTEXT_REL_PATH),
+    sha256: z.string().regex(/^[a-f0-9]{64}$/),
+    createdAt: z.string().datetime(),
+}).strict();
+function parseContext(value) {
+    try {
+        return projectGovernanceContextSchema.parse(value);
+    }
+    catch (error) {
+        throw new DagProjectGovernanceIntegrityError(`project governance context schema validation failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+}
+const writerChangeManifestArtifactSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    writerNodeId: z.string().min(1),
+    /** Runtime authorization used by the writer (optional on older manifests). */
+    effectiveWriteSet: z.array(z.string()).optional(),
+    approvalSourceNodeId: z.string().min(1).optional(),
+    approvalDigest: z.string().min(1).optional(),
+    changedFiles: z.array(z.string()),
+    beforeStatusSha256: z.string().regex(/^[a-f0-9]{64}$/),
+    afterStatusSha256: z.string().regex(/^[a-f0-9]{64}$/),
+})
+    .strict();
+/**
+ * Read run-owned manifests only for Pi nodes that actually finished with the
+ * bounded write tool profile. A finished writer without its manifest fails
+ * closed: otherwise the reviewer could incorrectly conclude that no project
+ * governance applies.
+ */
+export async function readCompletedWriterChangeManifests(input) {
+    const manifests = [];
+    for (const task of input.spec.tasks) {
+        if (task.executor !== "pi" || task.toolProfile !== "write")
+            continue;
+        if (input.state.nodes[task.id]?.status !== "FINISHED")
+            continue;
+        const artifactPath = path.join(input.runDir, task.id, "change-manifest.json");
+        let decoded;
+        try {
+            decoded = JSON.parse(await readFile(artifactPath, "utf-8"));
+        }
+        catch (error) {
+            throw new DagProjectGovernanceIntegrityError(`finished writer ${task.id} is missing a valid change-manifest.json: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+        const parsed = writerChangeManifestArtifactSchema.safeParse(decoded);
+        if (!parsed.success || parsed.data.writerNodeId !== task.id) {
+            throw new DagProjectGovernanceIntegrityError(`writer change manifest ownership/schema mismatch for ${task.id}`);
+        }
+        manifests.push({
+            writerNodeId: parsed.data.writerNodeId,
+            changedFiles: [...new Set(parsed.data.changedFiles)].sort(),
+        });
+    }
+    return manifests;
+}
+export async function writeProjectGovernanceContext(runDir, ctx) {
+    const parsed = parseContext(ctx);
+    const raw = serializeContext(parsed);
+    await writeTextAtomic(path.join(runDir, ...PROJECT_GOVERNANCE_CONTEXT_REL_PATH.split("/")), raw);
+    return {
+        schemaVersion: PROJECT_GOVERNANCE_CONTEXT_SCHEMA_VERSION,
+        resolverVersion: PROJECT_GOVERNANCE_CONTEXT_RESOLVER_VERSION,
+        path: PROJECT_GOVERNANCE_CONTEXT_REL_PATH,
+        sha256: sha256(raw),
+        createdAt: parsed.createdAt,
+    };
+}
+export async function readProjectGovernanceContext(runDir, refValue, options) {
+    let ref;
+    try {
+        ref = projectGovernanceContextRefSchema.parse(refValue);
+    }
+    catch (error) {
+        throw new DagProjectGovernanceIntegrityError(`project governance context ref is invalid: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+    const ctxPath = path.join(runDir, ...ref.path.split("/"));
+    let raw;
+    try {
+        raw = await readFile(ctxPath);
+    }
+    catch (error) {
+        throw new DagProjectGovernanceIntegrityError(`project governance context missing or unreadable at ${ref.path}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+    const actualHash = sha256(raw);
+    if (actualHash !== ref.sha256) {
+        throw new DagProjectGovernanceIntegrityError(`project governance context integrity check failed at ${ref.path}: expected sha256 ${ref.sha256}, got ${actualHash}`);
+    }
+    let decoded;
+    try {
+        decoded = JSON.parse(raw.toString("utf-8"));
+    }
+    catch (error) {
+        throw new DagProjectGovernanceIntegrityError(`project governance context JSON is invalid: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+    const ctx = parseContext(decoded);
+    if (ctx.createdAt !== ref.createdAt) {
+        throw new DagProjectGovernanceIntegrityError("project governance context ref metadata does not match the artifact");
+    }
+    if (options?.expectedRunId && ctx.runId !== options.expectedRunId) {
+        throw new DagProjectGovernanceIntegrityError(`project governance context run ownership mismatch: expected ${options.expectedRunId}, got ${ctx.runId}`);
+    }
+    return ctx;
+}

package/dist/workflows/dag/prompt-source.js

@@ -0,0 +1,88 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+const INLINE_PROMPT_FIELD = "subtask_prompt";
+const MARKDOWN_PROMPT_FIELD = "subtask_prompt_markdown";
+const HYPHENATED_MARKDOWN_PROMPT_FIELD = "subtask_prompt-markdown";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasOwn(record, key) {
+    return Object.hasOwn(record, key);
+}
+function taskLabel(task, index) {
+    return typeof task.id === "string" && task.id.trim() ? task.id : `#${index}`;
+}
+export function assertDagPromptSourceRule(raw, options) {
+    if (!isRecord(raw))
+        return;
+    if (!Array.isArray(raw.tasks))
+        return;
+    raw.tasks.forEach((taskRaw, index) => {
+        if (!isRecord(taskRaw))
+            return;
+        const label = taskLabel(taskRaw, index);
+        if (hasOwn(taskRaw, HYPHENATED_MARKDOWN_PROMPT_FIELD)) {
+            throw new Error(`task ${label} must use ${MARKDOWN_PROMPT_FIELD}, not ${HYPHENATED_MARKDOWN_PROMPT_FIELD}`);
+        }
+        const hasInline = hasOwn(taskRaw, INLINE_PROMPT_FIELD);
+        const hasMarkdown = hasOwn(taskRaw, MARKDOWN_PROMPT_FIELD);
+        if (hasInline === hasMarkdown) {
+            throw new Error(`task ${label} must contain exactly one of ${INLINE_PROMPT_FIELD} or ${MARKDOWN_PROMPT_FIELD}`);
+        }
+        if (hasInline) {
+            const prompt = taskRaw[INLINE_PROMPT_FIELD];
+            if (typeof prompt !== "string" || prompt.trim().length === 0) {
+                throw new Error(`task ${label} ${INLINE_PROMPT_FIELD} must be a non-empty string`);
+            }
+        }
+        if (hasMarkdown) {
+            if (!options.allowMarkdown) {
+                throw new Error(`task ${label} uses ${MARKDOWN_PROMPT_FIELD}; load DAGs with loadDagSpecFromFile so markdown prompts can be resolved`);
+            }
+            const markdownPath = taskRaw[MARKDOWN_PROMPT_FIELD];
+            if (typeof markdownPath !== "string" ||
+                markdownPath.trim().length === 0) {
+                throw new Error(`task ${label} ${MARKDOWN_PROMPT_FIELD} must be a non-empty string`);
+            }
+        }
+    });
+}
+export async function normalizeDagPromptSources(raw, dagDir) {
+    assertDagPromptSourceRule(raw, { allowMarkdown: true });
+    if (!isRecord(raw) || !Array.isArray(raw.tasks))
+        return raw;
+    const tasks = await Promise.all(raw.tasks.map(async (taskRaw, index) => {
+        if (!isRecord(taskRaw) || !hasOwn(taskRaw, MARKDOWN_PROMPT_FIELD)) {
+            return taskRaw;
+        }
+        const label = taskLabel(taskRaw, index);
+        const markdownPath = String(taskRaw[MARKDOWN_PROMPT_FIELD]);
+        const resolvedPath = path.resolve(dagDir, markdownPath);
+        let content;
+        try {
+            content = await readFile(resolvedPath, "utf-8");
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`failed to read ${MARKDOWN_PROMPT_FIELD} for task ${label}: ${resolvedPath}: ${message}`);
+        }
+        if (content.trim().length === 0) {
+            throw new Error(`task ${label} ${MARKDOWN_PROMPT_FIELD} resolved to an empty file: ${resolvedPath}`);
+        }
+        const { [MARKDOWN_PROMPT_FIELD]: _markdown, ...rest } = taskRaw;
+        return {
+            ...rest,
+            [INLINE_PROMPT_FIELD]: content,
+            subtask_prompt_source: {
+                type: "markdown",
+                path: markdownPath,
+                sha256: createHash("sha256").update(content).digest("hex"),
+            },
+        };
+    }));
+    return {
+        ...raw,
+        tasks,
+    };
+}