@tea-agent/loop-agent 0.16.25 → 0.17.0

package/dist/workflows/dag/node-execution.js

@@ -9,11 +9,12 @@ import { buildDagNodePromptEnvelope } from "./prompt.js";
 import { persistLongNodeOutputArtifacts } from "./upstream-artifacts.js";
 import { computeBackoffDelayMs, isRetryablePiFailureCategory, isSafeReadOnlyPiRetryCandidate, } from "./retry-policy.js";
 import { writeDagNodeJsonArtifact } from "../../infrastructure/harness/artifact-store.js";
+import { buildProjectGovernanceContext, readCompletedWriterChangeManifests, writeProjectGovernanceContext, } from "./project-governance-context.js";
 import { assertSkillSnapshotCoversSpec, buildNodePromptFromSnapshot, isDagSkillSnapshotIntegrityError, readSkillSnapshot, } from "./skill-snapshot.js";
 import { resolveDagSkillInstructions, skillInstructionMetadata, } from "./skill-instructions.js";
 import { parseRepairArtifactFromText, resolveRepairTaskForGate, validateRepairArtifactScope, } from "./repair-artifact.js";
 import { resolveModelForTask, } from "./types.js";
-export function buildNodePrompt(spec, task, upstream) {
+export function buildNodePrompt(spec, task, upstream, options) {
     const policy = resolveContextPolicy(spec);
     return buildDagNodePromptEnvelope({
         spec,
@@ -21,9 +22,27 @@ export function buildNodePrompt(spec, task, upstream) {
         upstream,
         resolvedSkills: policy.resolveSkills(spec, task),
         maxUpstreamChars: policy.resolveMaxUpstreamChars(task),
+        projectGovernanceContext: options?.projectGovernanceContext,
     });
 }
-export async function buildNodePromptWithResolvedSkillInstructions(spec, task, upstream, cwd) {
+function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFailureCategory) {
+    if (attemptNumber <= 1 ||
+        task.outputMode !== "structured-required" ||
+        previousFailureCategory !== "output-too-large") {
+        return basePrompt;
+    }
+    return [
+        basePrompt,
+        "",
+        "<retry_instruction>",
+        "Previous attempt exceeded the structured output size limit.",
+        "Return only the compact structured artifact required by this node's output contract.",
+        "Do not include explanatory prose, duplicated upstream context, long evidence excerpts, or additional markdown sections.",
+        "If a fenced JSON object is required, output exactly one fenced json block and nothing else.",
+        "</retry_instruction>",
+    ].join("\n");
+}
+export async function buildNodePromptWithResolvedSkillInstructions(spec, task, upstream, cwd, options) {
     const policy = resolveContextPolicy(spec);
     const skillNames = policy.resolveSkills(spec, task);
     const budget = policy.resolveSkillInstructionBudget(task);
@@ -43,6 +62,7 @@ export async function buildNodePromptWithResolvedSkillInstructions(spec, task, u
             resolvedSkills: skillNames,
             resolvedSkillInstructions,
             maxUpstreamChars: policy.resolveMaxUpstreamChars(task),
+            projectGovernanceContext: options?.projectGovernanceContext,
         }),
         resolvedSkills: skillInstructionMetadata(resolvedSkillInstructions),
     };
@@ -138,12 +158,12 @@ export async function executeDagNode(input) {
     const { nodeId, tasksById, state, spec, cwd, runDir, executeNode } = input;
     const task = tasksById.get(nodeId);
     const node = state.nodes[nodeId];
-    const failSkillSnapshot = async (error) => {
+    const failBeforePrompt = async (error, failureCategory) => {
         const failedAt = new Date().toISOString();
         node.startedAt ??= failedAt;
         node.status = "ERROR";
         node.stderr = error instanceof Error ? error.message : String(error);
-        node.failureCategory = "skill-snapshot-integrity";
+        node.failureCategory = failureCategory;
         node.finishedAt = failedAt;
         node.lastActivityAt = node.finishedAt;
         node.durationMs = Math.max(0, Date.now() - new Date(node.startedAt).getTime());
@@ -152,6 +172,29 @@ export async function executeDagNode(input) {
         await input.persistState();
         await notifyNodeObserver(input.observer, "onNodeFinish", nodeId, state);
     };
+    const failSkillSnapshot = (error) => failBeforePrompt(error, "skill-snapshot-integrity");
+    let projectGovernanceContext;
+    if (task.governanceStandardReview) {
+        try {
+            const changeManifest = await readCompletedWriterChangeManifests({
+                runDir,
+                spec,
+                state,
+            });
+            projectGovernanceContext = await buildProjectGovernanceContext({
+                runId: state.runId,
+                cwd,
+                changeManifest,
+                runDir,
+            });
+            state.projectGovernanceContextRef = await writeProjectGovernanceContext(runDir, projectGovernanceContext);
+            await input.persistState();
+        }
+        catch (error) {
+            await failBeforePrompt(error, "project-governance-integrity");
+            return;
+        }
+    }
     const isDynamicTask = Boolean(task.dynamicExpansion
         || task.dynamicReduction
         || task.dynamicCondition
@@ -169,6 +212,7 @@ export async function executeDagNode(input) {
                     task,
                     upstream: state.nodes,
                     snapshot: skillSnapshot,
+                    projectGovernanceContext,
                 });
             }
         }
@@ -237,7 +281,7 @@ export async function executeDagNode(input) {
         }
         else {
             ({ prompt, resolvedSkills } =
-                await buildNodePromptWithResolvedSkillInstructions(spec, task, state.nodes, cwd));
+                await buildNodePromptWithResolvedSkillInstructions(spec, task, state.nodes, cwd, { projectGovernanceContext }));
         }
     }
     catch (error) {
@@ -256,6 +300,7 @@ export async function executeDagNode(input) {
     const attempts = [];
     let totalBackoffMs = 0;
     let terminalResult;
+    let previousFailureCategory;
     for (let attemptNumber = 1; attemptNumber <= maxAttempts; attemptNumber += 1) {
         const attemptStartedAt = new Date().toISOString();
         const attemptStarted = Date.now();
@@ -266,7 +311,12 @@ export async function executeDagNode(input) {
                 tasksById,
                 state,
             });
-            result = await executeNode({ task, cwd, model, prompt });
+            result = await executeNode({
+                task,
+                cwd,
+                model,
+                prompt: buildAttemptPrompt(task, prompt, attemptNumber, previousFailureCategory),
+            });
         }
         catch (error) {
             result = {
@@ -329,6 +379,7 @@ export async function executeDagNode(input) {
             await input.persistState();
         }
         terminalResult = result;
+        previousFailureCategory = result.failureCategory;
         if (result.ok)
             break;
         const canRetry = retryPolicy !== undefined && attemptNumber < maxAttempts;

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

@@ -0,0 +1,508 @@
+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),
+    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;
+}