@tea-agent/loop-agent 0.16.25 → 0.16.26

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;
+}

package/dist/workflows/dag/prompt.js

@@ -98,8 +98,49 @@ function buildReadOnlyBoundary(writePolicy) {
         "Return findings in the assistant response/stdout only; the DAG runner persists node artifacts under .harness/dag-runs/<state>/<run-id>/<node-id>/.",
     ];
 }
+function formatProjectGovernanceContext(ctx) {
+    if (!ctx || !ctx.applicable)
+        return undefined;
+    const lines = [];
+    lines.push("Deterministic project governance manifest for the actual writer changeset of this run. Interpret it for compliance review; do not invent rules beyond the files and hashes listed here.");
+    lines.push("Before issuing a verdict, use read-only tools to read every applicable AGENTS.md and every mandatory referenced standard listed below from the repository; hashes bind the exact inputs for audit.");
+    lines.push("Your first non-empty output line must be exactly VERDICT: pass or VERDICT: request-revision. Request revision while any applicable mandatory instruction is violated.");
+    lines.push("");
+    lines.push("Change manifest (writer nodes and their changed files):");
+    for (const entry of ctx.changeManifest) {
+        if (entry.changedFiles.length === 0)
+            continue;
+        lines.push(`- ${entry.writerNodeId}: ${entry.changedFiles.join(", ")}`);
+    }
+    lines.push("");
+    lines.push("Applicable AGENTS.md chain (root -> nearest):");
+    for (const entry of ctx.agentsMdChain) {
+        lines.push(`- ${entry.path} (enforcement=mandatory, directory=${entry.directory || "/"}, sha256=${entry.sha256}, bytes=${entry.bytes}) applies to: ${entry.appliesTo.join(", ") || "(none)"}`);
+    }
+    if (ctx.referencedStandards.length > 0) {
+        lines.push("");
+        lines.push("Referenced repository-local code standards:");
+        for (const std of ctx.referencedStandards) {
+            lines.push(`- ${std.path} (enforcement=${std.enforcement}, from ${ctx.agentsMdChain[std.fromAgentsMd]?.path ?? "AGENTS.md"}, sha256=${std.sha256}, bytes=${std.bytes}, scope=${std.scope})`);
+        }
+    }
+    if (ctx.unresolvedReferences.length > 0) {
+        lines.push("");
+        lines.push("Unresolved reference diagnostics (structured, not read): for awareness only.");
+        for (const ref of ctx.unresolvedReferences) {
+            lines.push(`- ${ref.declaredPath}: ${ref.reason} (from ${ctx.agentsMdChain[ref.fromAgentsMd]?.path ?? "AGENTS.md"})`);
+        }
+    }
+    if (ctx.diagnostics.length > 0) {
+        lines.push("");
+        lines.push("Resolver diagnostics:");
+        for (const diag of ctx.diagnostics)
+            lines.push(`- ${diag}`);
+    }
+    return lines.join("\n");
+}
 export function buildDagNodePromptEnvelope(input) {
-    const { spec, task, upstream, resolvedSkills = [], resolvedSkillInstructions = [], maxUpstreamChars = MAX_UPSTREAM_CHARS, } = input;
+    const { spec, task, upstream, resolvedSkills = [], resolvedSkillInstructions = [], maxUpstreamChars = MAX_UPSTREAM_CHARS, projectGovernanceContext, } = input;
     const objective = spec.objective ?? spec.title;
     const successCriteria = formatBulletList(spec.successCriteria, "(none specified)");
     const globalConstraints = formatBulletList(spec.globalConstraints, "(none specified)");
@@ -150,6 +191,10 @@ export function buildDagNodePromptEnvelope(input) {
     else {
         sections.push("<upstream_context>\n(none)\n</upstream_context>");
     }
+    const governanceSection = formatProjectGovernanceContext(projectGovernanceContext);
+    if (governanceSection) {
+        sections.push(`<project_governance_context>\n${governanceSection}\n</project_governance_context>`);
+    }
     sections.push(`<task>\n${task.subtask_prompt}\n</task>`);
     return sections.join("\n\n");
 }

package/dist/workflows/dag/skill-snapshot.js

@@ -524,6 +524,7 @@ export function buildNodePromptFromSnapshot(input) {
             resolvedSkills: skillNames,
             resolvedSkillInstructions,
             maxUpstreamChars: policy.resolveMaxUpstreamChars(input.task),
+            projectGovernanceContext: input.projectGovernanceContext,
         }),
         resolvedSkills: resolvedSkillInstructions.map(stripPromptText),
     };

package/dist/workflows/dag/types.js

@@ -152,6 +152,9 @@ export const dagShellConfigSchema = z.object({
     commands: z.array(z.string()).default([]),
     preset: dagShellPresetSchema.optional(),
     verdictGate: dagVerdictGateSchema.optional(),
+    projectGovernanceGate: z.object({
+        contextPath: z.literal(".runtime/project-governance-context.json"),
+    }).strict().optional(),
     requirementCoverageGate: dagRequirementCoverageGateSchema.optional(),
     jsonArtifactGate: dagJsonArtifactGateSchema.optional(),
     backendTestPipeline: dagBackendTestPipelineSchema.optional(),
@@ -311,6 +314,13 @@ export const dagTaskSchema = z.object({
     static: dagStaticConfigSchema.optional(),
     outputContract: z.string().optional(),
     firstProtocolLine: z.string().min(1).optional(),
+    /**
+     * Explicit opt-in for the deterministic project governance context resolver
+     * (AGENTS.md chain + referenced code standards). Only tasks that set this
+     * to `true` receive a `<project_governance_context>` prompt section and
+     * closeout-blocking gate behavior. Never inferred from role/name.
+     */
+    governanceStandardReview: z.boolean().optional(),
     allowedPaths: z.array(z.string()).optional().default([]),
     forbiddenPaths: z.array(z.string()).optional().default([]),
     decisionGate: dagDecisionGateSchema.optional(),

package/dist/workflows/dag/validate.js

@@ -653,12 +653,40 @@ export function validateDagSpec(spec) {
         validateStaticTaskConfig(task, issues);
         validateDecisionGateTaskConfig(task, issues);
         validateRetryPolicyTaskConfig(task, issues);
+        validateProjectGovernanceTaskConfig(task, spec, issues);
     }
     validateSameRankWriteSetConflicts(spec, ranks, issues);
     validateSameRankAgentAttributionRisks(spec, ranks, issues);
     validateWriterSourceBinding(spec, issues);
     return issues;
 }
+function validateProjectGovernanceTaskConfig(task, spec, issues) {
+    if (task.governanceStandardReview) {
+        if (task.executor !== "pi" ||
+            task.toolProfile === "write" ||
+            !["read-only", "none"].includes((task.writePolicy ?? "read-only"))) {
+            issues.push({
+                type: "invalid-project-governance-config",
+                message: `task ${task.id} governanceStandardReview requires a read-only Pi node`,
+            });
+        }
+    }
+    if (!task.shell?.projectGovernanceGate)
+        return;
+    const verdictGate = task.shell.verdictGate;
+    const source = verdictGate
+        ? spec.tasks.find((candidate) => candidate.id === verdictGate.fromNodeId)
+        : undefined;
+    if (task.executor !== "shell" ||
+        !verdictGate ||
+        !task.depends_on.includes(verdictGate.fromNodeId) ||
+        !source?.governanceStandardReview) {
+        issues.push({
+            type: "invalid-project-governance-config",
+            message: `task ${task.id} projectGovernanceGate requires verdictGate over a directly-dependent governanceStandardReview node`,
+        });
+    }
+}
 export function assertValidDagSpec(spec, options = {}) {
     const issues = collectBlockingIssues(options.issues ?? validateDagSpec(spec), options);
     if (issues.length > 0) {

package/docs/templates/agent-dag.schema.json

@@ -241,6 +241,17 @@
             }
           }
         },
+        "projectGovernanceGate": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["contextPath"],
+          "properties": {
+            "contextPath": {
+              "const": ".runtime/project-governance-context.json",
+              "description": "Run-owned project governance context. When applicable=false the gate is a deterministic no-op; otherwise verdictGate remains authoritative."
+            }
+          }
+        },
         "requirementCoverageGate": {
           "type": "object", "additionalProperties": false,
           "required": ["fromNodeIds", "requiredIds"],
@@ -370,6 +381,10 @@
           "items": { "type": "string", "minLength": 1 }
         },
         "toolProfile": { "$ref": "#/$defs/toolProfile" },
+        "governanceStandardReview": {
+          "type": "boolean",
+          "description": "Explicitly opts this node into writer-change-scoped AGENTS.md and repository-local code-standard review. Never inferred from node id or role."
+        },
         "writePolicy": { "$ref": "#/$defs/writePolicy" },
         "writeSet": {
           "type": "array",

package/docs/templates/agent-dag.supervised-implementation.json

@@ -530,6 +530,7 @@
       "complexity": "HIGH",
       "executor": "pi",
       "role": "reviewer",
+      "governanceStandardReview": true,
       "writePolicy": "read-only",
       "allowedPaths": [
         "**"