jules-orchestrator-kit 0.8.1 → 0.9.3

package/src/config.mjs

@@ -0,0 +1,325 @@
+import { readFileSync, existsSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import { execSync } from "node:child_process";
+
+export class ConfigError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConfigError";
+  }
+}
+
+const DEFAULTS = {
+  version: 1,
+  provider: "jules",
+  verify: {},
+  scope: { deny: [], allow: [], protect: [] },
+  limits: {
+    diffKb: 75,
+    promptKb: 50,
+    dailyTasks: 300,
+    repairAttempts: 3,
+    concurrency: 1,
+    staggerMs: 1500,
+  },
+  isolation: "none",
+  runner: "local",
+  branchPrefix: "agent/",
+  baseBranch: "main",
+};
+
+export const BUILTIN_DENY = [
+  ".git/**",
+  "**/.env",
+  "**/.env.*",
+  "**/*.pem",
+  "**/*.key",
+  "**/id_rsa*",
+  ".agent/config.yml",
+  ".agent/jules.yml",
+  ".agent/jules-queue/**",
+  ".github/**",
+];
+
+export const BUILTIN_PROTECT = [
+  ".agent/rules/**",
+  "package.json",
+  "Cargo.toml",
+  "pyproject.toml",
+  "go.mod",
+  "Makefile",
+];
+
+const BLOCKED_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+function coerce(val) {
+  if (!val) return "";
+  if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+    return val.slice(1, -1);
+  }
+  if (val === "true") return true;
+  if (val === "false") return false;
+  if (!isNaN(Number(val)) && val.trim() !== "") return Number(val);
+  return val;
+}
+
+export function normalizePath(p) {
+  if (!p || typeof p !== "string") return "";
+  return p.split(sep).join("/").replace(/\\/g, "/");
+}
+
+export function resolveRoot(cwd = process.cwd()) {
+  try {
+    return execSync("git rev-parse --show-toplevel", { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch (_) {
+    return resolve(cwd);
+  }
+}
+
+export function dedupe(arr) {
+  return Array.from(new Set((arr || []).filter(Boolean)));
+}
+
+/**
+ * Single authoritative scope normalizer. Always merges BUILTIN_DENY and BUILTIN_PROTECT.
+ * CRITICAL FIX FOR B1: User scope.deny will add to BUILTIN_DENY, never replace it.
+ */
+export function normalizeScope(parsed = {}) {
+  const forbiddenPaths = Array.isArray(parsed.forbidden_paths)
+    ? parsed.forbidden_paths
+    : Array.isArray(parsed.scope?.deny)
+    ? parsed.scope.deny
+    : [];
+  const allowPaths = Array.isArray(parsed.allow_paths)
+    ? parsed.allow_paths
+    : Array.isArray(parsed.scope?.allow)
+    ? parsed.scope.allow
+    : [];
+  const protectPaths = Array.isArray(parsed.scope?.protect) ? parsed.scope.protect : [];
+
+  return {
+    deny: dedupe([...BUILTIN_DENY, ...forbiddenPaths]),
+    allow: dedupe(allowPaths),
+    protect: dedupe([...BUILTIN_PROTECT, ...protectPaths]),
+  };
+}
+
+/**
+ * Indent-stack zero-dependency YAML parser with prototype pollution protection.
+ */
+export function parseYaml(src) {
+  if (!src || typeof src !== "string") return Object.create(null);
+  const root = Object.create(null);
+  const stack = [{ indent: -1, node: root }];
+  const lines = src.split("\n");
+
+  for (let rawLine of lines) {
+    const commentIdx = rawLine.indexOf("#");
+    const line = commentIdx !== -1 ? rawLine.slice(0, commentIdx) : rawLine;
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+
+    const indent = rawLine.length - rawLine.trimStart().length;
+
+    while (stack.length > 1 && indent <= stack[stack.length - 1].indent) {
+      stack.pop();
+    }
+
+    const top = stack[stack.length - 1];
+
+    if (trimmed.startsWith("- ")) {
+      if (top.key && top.parent) {
+        if (!Array.isArray(top.parent[top.key])) {
+          top.parent[top.key] = [];
+        }
+        top.parent[top.key].push(coerce(trimmed.slice(2).trim()));
+      } else if (Array.isArray(top.node)) {
+        top.node.push(coerce(trimmed.slice(2).trim()));
+      }
+      continue;
+    }
+
+    const eqIdx = trimmed.indexOf(":");
+    if (eqIdx > 0) {
+      const rawKey = trimmed.slice(0, eqIdx).trim();
+      const valStr = trimmed.slice(eqIdx + 1).trim();
+
+      if (BLOCKED_KEYS.has(rawKey)) {
+        throw new ConfigError(`Illegal prototype key "${rawKey}" detected in configuration`);
+      }
+
+      if (valStr === "") {
+        const child = Object.create(null);
+        top.node[rawKey] = child;
+        stack.push({ indent, node: child, key: rawKey, parent: top.node });
+      } else if (valStr.startsWith("[") && valStr.endsWith("]")) {
+        const items = valStr
+          .slice(1, -1)
+          .split(",")
+          .map((s) => coerce(s.trim()))
+          .filter((s) => s !== "");
+        top.node[rawKey] = items;
+      } else {
+        top.node[rawKey] = coerce(valStr);
+      }
+    }
+  }
+
+  return root;
+}
+
+export function detectPackageManager(root = process.cwd(), pkg = {}) {
+  if (existsSync(join(root, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync(join(root, "yarn.lock"))) return "yarn";
+  if (existsSync(join(root, "bun.lockb"))) return "bun";
+  if (existsSync(join(root, "package-lock.json"))) return "npm";
+
+  const pm = pkg.packageManager;
+  if (typeof pm === "string") {
+    if (pm.startsWith("pnpm")) return "pnpm";
+    if (pm.startsWith("yarn")) return "yarn";
+    if (pm.startsWith("bun")) return "bun";
+    if (pm.startsWith("npm")) return "npm";
+  }
+
+  return "npm";
+}
+
+/**
+ * Autodetects verification test/build commands across 16 common tech stacks.
+ */
+export function detectStack(projectRoot = process.cwd()) {
+  const detectors = [
+    {
+      files: ["turbo.json"],
+      resolve: () => ({ testCmd: "npx turbo run test", buildCmd: "npx turbo run build", stack: "turbo" }),
+    },
+    {
+      files: ["pnpm-workspace.yaml"],
+      resolve: () => ({ testCmd: "pnpm -r test", buildCmd: "pnpm -r build", stack: "pnpm" }),
+    },
+    {
+      files: ["nx.json"],
+      resolve: () => ({ testCmd: "npx nx run-many -t test", buildCmd: "npx nx run-many -t build", stack: "nx" }),
+    },
+    {
+      files: ["bunfig.toml", "bun.lockb"],
+      resolve: () => ({ testCmd: "bun test", buildCmd: "bun run build", stack: "bun" }),
+    },
+    {
+      files: ["deno.json", "deno.jsonc"],
+      resolve: () => ({ testCmd: "deno test", buildCmd: "deno task build", stack: "deno" }),
+    },
+    {
+      files: ["package.json"],
+      resolve: (root) => {
+        try {
+          const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf-8"));
+          const pm = detectPackageManager(root, pkg);
+          const scripts = pkg.scripts || {};
+          let testScript = scripts.test ? `${pm} test` : "";
+          const buildScript = scripts.build ? `${pm} run build` : "";
+          return { testCmd: testScript || `${pm} test`, buildCmd: buildScript, stack: "node" };
+        } catch (_) {
+          return { testCmd: "npm test", buildCmd: "npm run build", stack: "node" };
+        }
+      },
+    },
+    {
+      files: ["Cargo.toml"],
+      resolve: () => ({ testCmd: "cargo test --workspace", buildCmd: "cargo build", stack: "cargo" }),
+    },
+    {
+      files: ["go.mod"],
+      resolve: () => ({ testCmd: "go test ./...", buildCmd: "go build ./...", stack: "go" }),
+    },
+    {
+      files: ["pyproject.toml", "requirements.txt", "setup.py"],
+      resolve: () => ({ testCmd: "pytest", buildCmd: "", stack: "python" }),
+    },
+    {
+      files: ["mix.exs"],
+      resolve: () => ({ testCmd: "mix test", buildCmd: "mix compile", stack: "mix" }),
+    },
+    {
+      files: ["Gemfile"],
+      resolve: () => ({ testCmd: "bundle exec rake test", buildCmd: "", stack: "bundler" }),
+    },
+    {
+      files: ["Package.swift"],
+      resolve: () => ({ testCmd: "swift test", buildCmd: "swift build", stack: "swift" }),
+    },
+    {
+      files: ["pom.xml"],
+      resolve: () => ({ testCmd: "mvn test", buildCmd: "mvn compile", stack: "maven" }),
+    },
+    {
+      files: ["build.gradle", "build.gradle.kts"],
+      resolve: () => ({ testCmd: "./gradlew test", buildCmd: "./gradlew assemble", stack: "gradle" }),
+    },
+    {
+      files: ["Makefile"],
+      resolve: () => ({ testCmd: "make test", buildCmd: "make build", stack: "make" }),
+    },
+  ];
+
+  for (const detector of detectors) {
+    if (detector.files.some((f) => existsSync(join(projectRoot, f)))) {
+      const res = detector.resolve(projectRoot);
+      if (res) return res;
+    }
+  }
+
+  return { testCmd: "", buildCmd: "", stack: "unknown" };
+}
+
+export function resolveVerify(root = process.cwd()) {
+  const s = detectStack(root);
+  return { test: s.testCmd || "", build: s.buildCmd || "" };
+}
+
+/**
+ * Loads and validates configuration from .agent/config.yml or .agent/jules.yml.
+ */
+export function loadConfig(root = resolveRoot(), explicitPath = null) {
+  const candidates = explicitPath
+    ? [explicitPath]
+    : [join(root, ".agent/config.yml"), join(root, ".agent/jules.yml")];
+
+  const configFile = candidates.find(existsSync);
+  let parsed = Object.create(null);
+  if (configFile) {
+    try {
+      const raw = readFileSync(configFile, "utf-8");
+      parsed = parseYaml(raw);
+    } catch (err) {
+      if (err instanceof ConfigError) throw err;
+    }
+  }
+
+  const testCmd = parsed.test_cmd || parsed.verify?.test || "";
+  const buildCmd = parsed.build_cmd || parsed.verify?.build || "";
+  const autoVerify = resolveVerify(root);
+
+  const config = {
+    version: parsed.version || DEFAULTS.version,
+    provider: parsed.provider || DEFAULTS.provider,
+    verify: {
+      test: testCmd || autoVerify.test,
+      build: buildCmd || autoVerify.build,
+    },
+    scope: normalizeScope(parsed),
+    limits: {
+      ...DEFAULTS.limits,
+      ...(parsed.limits || {}),
+    },
+    isolation: parsed.isolation || DEFAULTS.isolation,
+    runner: parsed.runner || DEFAULTS.runner,
+    branchPrefix: parsed.branch_prefix || parsed.branchPrefix || DEFAULTS.branchPrefix,
+    baseBranch: parsed.base_branch || parsed.baseBranch || DEFAULTS.baseBranch,
+    _root: root,
+    _file: configFile || null,
+  };
+
+  return config;
+}

package/src/engine.mjs

@@ -0,0 +1,217 @@
+import { loadConfig, parseYaml, normalizeScope } from "./config.mjs";
+import { checkScope, scanDiff, redactSecrets } from "./security.mjs";
+import { changedFiles, diffBytes, diffText, showFromOrigin, runCmd } from "./git.mjs";
+import { createProvider } from "./provider.mjs";
+import { withBudget, appendLedger, getQueueDir, ensureDir } from "./state.mjs";
+import { readdirSync, readFileSync, renameSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Gatekeeper verification engine (Phase 1: Scope, Phase 2: Payload, Phase 3: Secrets, Phase 4: Verify Commands).
+ * FAILS CLOSED ON GIT OR CONFIG ERRORS.
+ */
+export async function gate(opts = {}) {
+  const root = opts.root || process.cwd();
+  const config = opts.config || loadConfig(root);
+  const base = opts.base || config.baseBranch || "main";
+  const phases = [];
+
+  let files = [];
+  let bytes = 0;
+  let diffStr = "";
+
+  try {
+    files = changedFiles(root, base);
+    bytes = diffBytes(root, base);
+    diffStr = diffText(root, base);
+  } catch (err) {
+    phases.push({ phase: "git_resolution", ok: false, error: err.message });
+    return { ok: false, code: 1, phases, error: err.message };
+  }
+
+  // Phase 1: Scope Guard (Fetch trusted config strictly from origin/base using single normalizeScope)
+  let trustedScope = config.scope;
+  let trustedVerify = config.verify;
+
+  const trustedConfigRaw = showFromOrigin(root, base, ".agent/config.yml") || showFromOrigin(root, base, ".agent/jules.yml");
+  if (trustedConfigRaw) {
+    try {
+      const parsed = parseYaml(trustedConfigRaw);
+      // CRITICAL B1 FIX: normalizeScope ensures BUILTIN_DENY is ALWAYS merged with user deny rules
+      trustedScope = normalizeScope(parsed);
+      if (parsed.verify || parsed.test_cmd || parsed.build_cmd) {
+        trustedVerify = {
+          test: parsed.verify?.test || parsed.test_cmd || config.verify.test,
+          build: parsed.verify?.build || parsed.build_cmd || config.verify.build,
+        };
+      }
+    } catch (_) {}
+  } else {
+    // CRITICAL H-c FIX: Fall back strictly to normalizeScope({}) (built-ins only), never HEAD config
+    trustedScope = normalizeScope({});
+  }
+
+  const scopeResult = checkScope(files, trustedScope, {
+    allowProtected: opts.allowProtected || process.env.JULES_ALLOW_COMMAND_FILE_CHANGES === "true",
+  });
+
+  phases.push({ phase: "scope", ok: scopeResult.ok, violations: scopeResult.violations });
+  if (!scopeResult.ok) {
+    return { ok: false, code: 3, phases };
+  }
+
+  // Phase 2: Diff Payload Governor
+  const limitBytes = (config.limits.diffKb || 75) * 1024;
+  const payloadOk = bytes <= limitBytes;
+  phases.push({ phase: "payload", ok: payloadOk, bytes, limitBytes });
+  if (!payloadOk) {
+    return { ok: false, code: 5, phases };
+  }
+
+  // Phase 3: Diff Secret Scanner
+  const secretResult = scanDiff(diffStr);
+  phases.push({ phase: "secrets", ok: secretResult.ok, findings: secretResult.findings });
+  if (!secretResult.ok) {
+    return { ok: false, code: 6, phases };
+  }
+
+  // Phase 4: Automated Test & Build Verification (Uses trusted verify commands only)
+  const testCmd = trustedVerify.test;
+  const buildCmd = trustedVerify.build;
+  let testResult = { ok: true, status: 0 };
+  let buildResult = { ok: true, status: 0 };
+
+  if (testCmd) {
+    const res = runCmd(testCmd, { cwd: root, ignoreError: true });
+    testResult = { ok: res.status === 0, status: res.status, stdout: res.stdout, stderr: res.stderr, command: testCmd };
+  }
+
+  if (testResult.ok && buildCmd) {
+    const res = runCmd(buildCmd, { cwd: root, ignoreError: true });
+    buildResult = { ok: res.status === 0, status: res.status, stdout: res.stdout, stderr: res.stderr, command: buildCmd };
+  }
+
+  const verifyOk = testResult.ok && buildResult.ok;
+  const failingCmd = !testResult.ok ? testResult : !buildResult.ok ? buildResult : null;
+  phases.push({ phase: "verify", ok: verifyOk, testResult, buildResult });
+
+  if (!verifyOk && opts.fix) {
+    const repairs = await repair(failingCmd, { config, root, signal: opts.signal });
+    if (repairs.ok) {
+      return { ok: true, code: 0, phases, repairs };
+    }
+    return { ok: false, code: 4, phases, repairs };
+  }
+
+  return { ok: verifyOk, code: verifyOk ? 0 : 4, phases };
+}
+
+export async function repair(failure, opts = {}) {
+  const root = opts.root || process.cwd();
+  const config = opts.config || loadConfig(root);
+  const maxRetries = config.limits.repairAttempts || 3;
+  const provider = createProvider(config.provider, config);
+  const attempts = [];
+
+  let currentFailure = failure;
+  for (let n = 1; n <= maxRetries; n++) {
+    const repairPrompt = buildRepairPrompt(currentFailure, n, config);
+    let session;
+    try {
+      session = await withBudget(
+        () =>
+          provider.dispatch(
+            { id: `repair-${n}`, title: `OODA Auto-Repair Attempt ${n}`, prompt: repairPrompt },
+            { root, dryRun: opts.dryRun }
+          ),
+        root,
+        config.limits.dailyTasks
+      );
+    } catch (err) {
+      attempts.push({ n, ok: false, error: err.message });
+      break;
+    }
+
+    attempts.push({ n, session, ok: true });
+
+    // Re-verify after repair attempt
+    const gateRes = await gate({ root, config, fix: false });
+    if (gateRes.ok) {
+      return { ok: true, attempts, finalStatus: "PASSED" };
+    }
+    currentFailure = gateRes.phases.find((p) => p.phase === "verify")?.testResult || failure;
+  }
+
+  return { ok: false, attempts, finalStatus: "OODA_EXHAUSTED" };
+}
+
+function buildRepairPrompt(failure, attempt, _config) {
+  const cleanStderr = redactSecrets(failure.stderr || failure.stdout || "Unknown Error");
+  return `Auto-Repair Attempt #${attempt}
+Command Failed: ${failure.command || "verify"}
+
+REPAIR DIRECTIVE & STRICT INVARIANTS:
+1. Ground your fix strictly in the error log below. Do NOT guess file contents or function signatures.
+2. NO WEAKENING: You are STRICTLY FORBIDDEN from deleting tests, commenting out assertions, or weakening expectations to achieve a passing test. Leave unmet requirements RED if the requirement is valid and feature code is missing.
+3. CARRY EVIDENCE: Address the root cause directly and verify the exact fix.
+4. RE-VERIFY: Execute full verification after patching to ensure zero new regressions.
+
+Stderr:
+${cleanStderr}`;
+}
+
+export async function dispatch(task, opts = {}) {
+  const root = opts.config?._root || opts.root || process.cwd();
+  const config = opts.config || loadConfig(root);
+  const provider = createProvider(config.provider, config);
+
+  // Enforce prompt size limit
+  const promptKb = (config.limits.promptKb || 50) * 1024;
+  if (task.prompt && Buffer.byteLength(task.prompt, "utf-8") > promptKb) {
+    throw new Error(`Task prompt exceeds maximum payload limit of ${config.limits.promptKb} KB`);
+  }
+
+  // Redact secrets in prompt before dispatching
+  const cleanPrompt = redactSecrets(task.prompt);
+  const cleanTask = { ...task, prompt: cleanPrompt };
+
+  return withBudget(
+    () => provider.dispatch(cleanTask, { root, dryRun: opts.dryRun }),
+    root,
+    config.limits.dailyTasks
+  );
+}
+
+export async function run(opts = {}) {
+  const root = opts.root || process.cwd();
+  const config = opts.config || loadConfig(root);
+  const concurrency = opts.concurrency || config.limits.concurrency || 1;
+  const queueDir = getQueueDir(root);
+  const completedDir = join(queueDir, "completed");
+  ensureDir(completedDir);
+
+  const files = readdirSync(queueDir).filter((f) => f.endsWith(".md"));
+  const results = [];
+
+  for (let i = 0; i < files.length; i += concurrency) {
+    const batch = files.slice(i, i + concurrency);
+    await Promise.all(
+      batch.map(async (file) => {
+        const srcPath = join(queueDir, file);
+        try {
+          const content = readFileSync(srcPath, "utf-8");
+          const task = { title: file, prompt: content };
+          const session = await dispatch(task, { root, config, dryRun: opts.dryRun });
+          const dstPath = join(completedDir, file);
+          renameSync(srcPath, dstPath);
+          appendLedger({ event: "task_completed", file, session }, root);
+          results.push({ file, ok: true, session });
+        } catch (err) {
+          results.push({ file, ok: false, error: err.message });
+        }
+      })
+    );
+  }
+
+  return { processed: results.length, results };
+}

package/src/envelope.mjs

@@ -0,0 +1,105 @@
+import { git, resolveBase } from "./git.mjs";
+import { checkScope } from "./security.mjs";
+import { normalizeScope } from "./config.mjs";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Validates a Task Envelope before dispatch or during CI triage.
+ * Prevents execution on fabricated premises (missing files/tests) or stale bases.
+ *
+ * @param {Object} envelope - Task envelope payload
+ * @param {Object} [opts] - Options (root, maxBehindCommits, maxBaseAgeHours)
+ * @returns {{ ok: boolean, code?: number, errors: string[], warnings: string[] }}
+ */
+export function validateEnvelope(envelope = {}, opts = {}) {
+  const root = opts.root || process.cwd();
+  const maxBehind = opts.maxBehindCommits ?? 25;
+  const maxAgeHours = opts.maxBaseAgeHours ?? 24;
+  const errors = [];
+  const warnings = [];
+
+  if (!envelope || typeof envelope !== "object") {
+    return { ok: false, code: 1, errors: ["Envelope must be a non-null object"], warnings: [] };
+  }
+
+  // 1. Mandatory Fields
+  if (!envelope.intent || typeof envelope.intent !== "string" || !envelope.intent.trim()) {
+    errors.push("Envelope missing required 'intent' string.");
+  }
+
+  // 2. Base Commit & Freshness Check
+  const baseCommit = envelope.base_commit || "main";
+  let resolvedBase = null;
+  try {
+    resolvedBase = resolveBase(root, baseCommit);
+  } catch (_) {
+    try {
+      resolvedBase = resolveBase(root, "HEAD");
+    } catch (_) {
+      resolvedBase = null;
+    }
+  }
+
+  if (resolvedBase) {
+    try {
+      const behindStr = git(["rev-list", "--count", `${resolvedBase}..origin/main`], { cwd: root, ignoreError: true });
+      const behindCount = parseInt(behindStr || "0", 10);
+      if (!isNaN(behindCount) && behindCount > maxBehind) {
+        errors.push(`Stale base commit: base is ${behindCount} commits behind origin/main (max allowed: ${maxBehind}).`);
+      }
+
+      const commitTimeStr = git(["show", "-s", "--format=%ct", resolvedBase], { cwd: root, ignoreError: true });
+      const commitTimestamp = parseInt(commitTimeStr || "0", 10);
+      if (commitTimestamp > 0) {
+        const nowSec = Math.floor(Date.now() / 1000);
+        const ageHours = (nowSec - commitTimestamp) / 3600;
+        if (ageHours > maxAgeHours) {
+          warnings.push(`Base commit is ${Math.round(ageHours)}h old (exceeds recommended ${maxAgeHours}h).`);
+        }
+      }
+    } catch (_) {
+      // Git commit range checks are non-blocking if origin/main is not fetched locally
+    }
+  }
+
+  // 3. Premise Check: Referenced Paths Must Exist
+  if (Array.isArray(envelope.referenced_paths)) {
+    for (const relPath of envelope.referenced_paths) {
+      if (typeof relPath !== "string") continue;
+      const absPath = join(root, relPath);
+      let existsInGit = false;
+      if (resolvedBase) {
+        const catRes = git(["cat-file", "-e", `${resolvedBase}:${relPath}`], { cwd: root, ignoreError: true });
+        existsInGit = typeof catRes === "string" && catRes.trim() !== "";
+      }
+      const existsOnDisk = existsSync(absPath);
+      if (!existsInGit && !existsOnDisk) {
+        errors.push(`Premise failure: referenced path '${relPath}' does not exist at base '${baseCommit}' or on disk.`);
+      }
+    }
+  }
+
+  // 4. Allowed Paths & Protected Scope Check
+  if (Array.isArray(envelope.allowed_paths) && envelope.allowed_paths.length > 0) {
+    const scope = normalizeScope(opts.scopeConfig || {});
+    const scopeCheck = checkScope(envelope.allowed_paths, scope);
+    if (!scopeCheck.ok) {
+      errors.push(`Allowed paths violate protected scope: ${scopeCheck.violations.map(v => `${v.file} (${v.reason})`).join(", ")}`);
+    }
+  }
+
+  // 5. Acceptance Criteria
+  if (envelope.acceptance_criteria !== undefined) {
+    if (!Array.isArray(envelope.acceptance_criteria) || envelope.acceptance_criteria.length === 0) {
+      errors.push("acceptance_criteria must be a non-empty array of strings when provided.");
+    }
+  }
+
+  return {
+    ok: errors.length === 0,
+    code: errors.length === 0 ? 0 : 1,
+    errors,
+    warnings,
+  };
+}