jules-orchestrator-kit 0.73.0 → 0.74.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "jules-orchestrator-kit",
-  "version": "0.73.0",
-  "description": "Zero-dependency safety gatekeeper, test oracle generator, and multi-agent coordination protocol for autonomous coding agents — Google Jules, Claude Code, Codex and Gemini CLI.",
+  "version": "0.74.0",
+  "description": "Zero-dependency safety gatekeeper, test oracle generator, and multi-agent coordination protocol for autonomous coding agents \u2014 Google Jules, Claude Code, Codex and Gemini CLI.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/FullThrottle83/jules-orchestrator-kit.git"
@@ -33,9 +33,7 @@
     ".agent/rules/",
     ".agent/prompts/",
     ".agent/workflows/",
-    "CHANGELOG.md",
-    "ROADMAP_V1.md",
-    "AGENTS.md"
+    "CHANGELOG.md"
   ],
   "scripts": {
     "init": "node bin/init.js",

package/scripts/validate-envelope.mjs

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 
 import { readFileSync, existsSync } from "node:fs";
-import { validateEnvelope } from "../src/envelope.mjs";
+import { validateEnvelope, parseEnvelopeHeader } from "../src/envelope.mjs";
 
 const args = process.argv.slice(2);
 const envelopeFile = args[0];
 
 if (!envelopeFile) {
-  console.log("Usage: node scripts/validate-envelope.mjs <path-to-envelope.json>");
+  console.log("Usage: node scripts/validate-envelope.mjs <path-to-envelope.json|path-to-task.md>");
   process.exit(1);
 }
 
@@ -18,7 +18,26 @@ if (!existsSync(envelopeFile)) {
 
 try {
   const content = readFileSync(envelopeFile, "utf-8");
-  const payload = JSON.parse(content);
+  let payload = null;
+  if (envelopeFile.endsWith(".json")) {
+    payload = JSON.parse(content);
+  } else {
+    payload = parseEnvelopeHeader(content);
+    if (!payload) {
+      try {
+        payload = JSON.parse(content);
+      } catch {
+        payload = null;
+      }
+    }
+  }
+
+  if (!payload || typeof payload !== "object") {
+    console.error("❌ TASK ENVELOPE PREMISE VALIDATION FAILED:");
+    console.error("  - File does not contain a valid JSON payload or task envelope frontmatter.");
+    process.exit(1);
+  }
+
   const res = validateEnvelope(payload);
 
   if (!res.ok) {
@@ -39,6 +58,6 @@ try {
   console.log("✅ Task envelope validated successfully.");
   process.exit(0);
 } catch (err) {
-  console.error(`❌ Invalid JSON or execution error: ${err.message}`);
+  console.error(`❌ Invalid envelope or execution error: ${err.message}`);
   process.exit(1);
 }

package/src/dag-engine.mjs

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { readFileSync, existsSync } from "node:fs";
 import { appendTelemetry } from "./telemetry.mjs";
+import { parseEnvelopeHeader } from "./envelope.mjs";
 
 /**
  * Custom error thrown when a circular dependency is detected in the DAG.
@@ -495,20 +496,19 @@ export async function executeQueueDag(root = process.cwd(), options = {}) {
 
     let targetFiles = [];
 
-    // Check envelope header
-    const match = content.match(/<!--\s*JULES_TASK_ENVELOPE:\s*({[\s\S]*?})\s*-->/);
-    if (match) {
-      try {
-        const meta = JSON.parse(match[1]);
-        if (meta.id) taskId = meta.id;
-        if (meta.title) title = meta.title;
-        if (meta.role) role = meta.role;
-        if (meta.tier) tier = meta.tier;
-        if (Array.isArray(meta.targetFiles)) targetFiles = meta.targetFiles;
-        else if (Array.isArray(meta.referenced_paths)) targetFiles = meta.referenced_paths;
-        if (Array.isArray(meta.dependsOn)) dependsOn = meta.dependsOn;
-        else if (typeof meta.dependsOn === "string") dependsOn = meta.dependsOn.split(",").map((s) => s.trim()).filter(Boolean);
-      } catch (_) {}
+    // Check envelope header (supports agentctl.task/v1 YAML frontmatter and legacy HTML comment)
+    const header = parseEnvelopeHeader(content);
+    if (header) {
+      if (header.id || header.taskId) taskId = header.id || header.taskId;
+      if (header.title) title = header.title;
+      if (header.role) role = header.role;
+      if (header.tier) tier = header.tier;
+      if (Array.isArray(header.targetFiles)) targetFiles = header.targetFiles;
+      else if (Array.isArray(header.referenced_paths)) targetFiles = header.referenced_paths;
+      else if (Array.isArray(header.allowed_paths)) targetFiles = header.allowed_paths;
+      else if (header.scope && Array.isArray(header.scope.allow)) targetFiles = header.scope.allow;
+      if (Array.isArray(header.dependsOn)) dependsOn = header.dependsOn;
+      else if (typeof header.dependsOn === "string") dependsOn = header.dependsOn.split(",").map((s) => s.trim()).filter(Boolean);
     } else if (file.endsWith(".json")) {
       try {
         const parsed = JSON.parse(content);

package/src/engine.mjs

@@ -143,6 +143,7 @@ export function fingerprintFailureState(failure = {}, root = process.cwd()) {
  * FAILS CLOSED ON GIT OR CONFIG ERRORS.
  */
 export async function gate(opts = {}) {
+  opts = opts && typeof opts === "object" ? { ...opts, fix: false } : { fix: false };
   const root = opts.root || process.cwd();
   const mode = opts.mode || (opts.workingTree ? "working-tree" : (process.env.JULES_GATE_MODE || "working-tree"));
   const config = opts.config || (mode === "working-tree" ? loadConfig(root) : null);
@@ -999,7 +1000,7 @@ export async function checkTaskPremise(task = {}, opts = {}) {
 
 /**
  * Session states the API documents as final. The full `SessionState` enum is
- * transcribed in `docs/jules-quality-plan.md`.
+ * transcribed in `docs/archive/jules-quality-plan.md`.
  */
 export const TERMINAL_SESSION_STATES = new Set(["COMPLETED", "FAILED"]);
 

package/src/envelope.mjs

@@ -24,12 +24,15 @@ export function validateEnvelope(envelope = {}, opts = {}) {
   }
 
   // 1. Mandatory Fields
-  if (!envelope.intent || typeof envelope.intent !== "string" || !envelope.intent.trim()) {
+  const rawIntent = (envelope.intent && typeof envelope.intent === "object")
+    ? envelope.intent.outcome
+    : (envelope.intent || envelope.title || envelope.prompt);
+  if (!rawIntent || typeof rawIntent !== "string" || !rawIntent.trim()) {
     errors.push("Envelope missing required 'intent' string.");
   }
 
   // 2. Base Commit & Freshness Check
-  const baseCommit = envelope.base_commit || "main";
+  const baseCommit = envelope.base_commit || envelope.baseCommit || envelope.base_sha || envelope.baseSha || "main";
   let resolvedBase = null;
   try {
     resolvedBase = resolveBase(root, baseCommit);
@@ -86,19 +89,51 @@ export function validateEnvelope(envelope = {}, opts = {}) {
   }
 
   // 4. Allowed Paths & Protected Scope Check
-  if (Array.isArray(envelope.allowed_paths) && envelope.allowed_paths.length > 0) {
+  const riskObj = envelope.risk && typeof envelope.risk === "object" ? envelope.risk : {};
+  const rawLane = riskObj.lane || envelope.risk_lane || envelope.riskLane;
+  const riskLane = rawLane ? String(rawLane).toLowerCase() : (envelope.flags?.requirePlanApproval ? "amber" : "green");
+  const allowProtected = opts.allowProtected ?? (riskLane === "amber" && Boolean(envelope.flags?.requirePlanApproval || riskObj.require_plan_approval));
+
+  if (riskLane === "red") {
+    errors.push("Red-lane tasks are outside autonomous agent delegation boundaries (unsupervised high-impact, custom crypto, un-oracleable).");
+  } else if (riskLane === "orange") {
+    warnings.push("Orange-lane task: candidate generation only. Execution must be conducted outside Jules via protected control plane.");
+  }
+
+  const allowPaths = envelope.allowed_paths || envelope.scope?.allow;
+  if (Array.isArray(allowPaths) && allowPaths.length > 0) {
     const scope = normalizeScope(opts.scopeConfig || {});
-    const scopeCheck = checkScope(envelope.allowed_paths, scope);
+    const scopeCheck = checkScope(allowPaths, scope, { allowProtected });
     if (!scopeCheck.ok) {
-      errors.push(`Allowed paths violate protected scope: ${scopeCheck.violations.map(v => `${v.file} (${v.reason})`).join(", ")}`);
+      const hasProtectedViolation = scopeCheck.violations.some((v) => v.rule === "protect");
+      if (hasProtectedViolation && !allowProtected) {
+        errors.push(
+          `Allowed paths violate protected scope: ${scopeCheck.violations.map((v) => `${v.file} (${v.reason})`).join(", ")}. Modifying protected paths requires risk.lane 'amber' and requirePlanApproval: true.`
+        );
+      } else {
+        errors.push(`Allowed paths violate protected scope: ${scopeCheck.violations.map((v) => `${v.file} (${v.reason})`).join(", ")}`);
+      }
     }
   }
 
-  // 5. Acceptance Criteria
+  // 5. Acceptance Criteria & Verification Commands
   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.");
     }
+  } else if (envelope.verification?.commands !== undefined) {
+    if (!Array.isArray(envelope.verification.commands) || envelope.verification.commands.length === 0) {
+      errors.push("verification.commands must be a non-empty array of strings when provided.");
+    }
+  }
+
+  if (envelope.verification && typeof envelope.verification === "object") {
+    if (envelope.verification.require_nonzero_test_count !== undefined && typeof envelope.verification.require_nonzero_test_count !== "boolean") {
+      errors.push("verification.require_nonzero_test_count must be a boolean when provided.");
+    }
+    if (envelope.verification.trusted_base !== undefined && typeof envelope.verification.trusted_base !== "string") {
+      errors.push("verification.trusted_base must be a string when provided.");
+    }
   }
 
   // 6. Concurrency Group Check
@@ -108,8 +143,49 @@ export function validateEnvelope(envelope = {}, opts = {}) {
     }
   }
 
-  return {
+  // 7. Invariants Check
+  if (envelope.invariants !== undefined && !Array.isArray(envelope.invariants)) {
+    errors.push("invariants must be an array of strings when provided.");
+  }
+
+  // 8. MCP Directives Check
+  if (envelope.mcp_directives !== undefined && !Array.isArray(envelope.mcp_directives)) {
+    errors.push("mcp_directives must be an array of strings when provided.");
+  }
+
+  // 9. Risk Object Check
+  if (envelope.risk !== undefined) {
+    if (typeof envelope.risk !== "object" || envelope.risk === null) {
+      errors.push("risk must be an object when provided.");
+    } else {
+      if (envelope.risk.lane !== undefined && !["green", "amber", "orange", "red"].includes(String(envelope.risk.lane).toLowerCase())) {
+        errors.push("risk.lane must be one of 'green', 'amber', 'orange', 'red' when provided.");
+      }
+      if (envelope.risk.require_plan_approval !== undefined && typeof envelope.risk.require_plan_approval !== "boolean") {
+        errors.push("risk.require_plan_approval must be a boolean when provided.");
+      }
+    }
+  }
 
+  // 10. Circuit Breaker Check
+  const cb = envelope.circuit_breaker || envelope.circuitBreaker;
+  if (cb !== undefined) {
+    if (typeof cb !== "object" || cb === null) {
+      errors.push("circuitBreaker must be an object when provided.");
+    } else {
+      if (cb.max_attempts !== undefined && !Number.isInteger(Number(cb.max_attempts))) {
+        errors.push("circuitBreaker.max_attempts must be an integer when provided.");
+      }
+      if (cb.max_diff_lines !== undefined && !Number.isInteger(Number(cb.max_diff_lines))) {
+        errors.push("circuitBreaker.max_diff_lines must be an integer when provided.");
+      }
+      if (cb.stop_if_same_failure_repeats !== undefined && typeof cb.stop_if_same_failure_repeats !== "boolean") {
+        errors.push("circuitBreaker.stop_if_same_failure_repeats must be a boolean when provided.");
+      }
+    }
+  }
+
+  return {
     ok: errors.length === 0,
     code: errors.length === 0 ? 0 : 1,
     errors,
@@ -118,18 +194,343 @@ export function validateEnvelope(envelope = {}, opts = {}) {
 }
 
 /**
- * Parse JSON metadata payload embedded in HTML comment JULES_TASK_ENVELOPE.
+ * Parses a subset of YAML suitable for task envelopes without third-party dependencies.
+ * Handles mappings, sequence lists, inline lists, quoted strings, numbers, and booleans.
+ *
+ * @param {string} yamlText
+ * @returns {Record<string, any>}
+ */
+export function parseYamlSubset(yamlText) {
+  if (!yamlText || typeof yamlText !== "string") return {};
+  const lines = yamlText.split(/\r?\n/);
+  const root = {};
+  const stack = [{ indent: -1, obj: root, key: null }];
+
+  function parseVal(raw) {
+    const trimmed = raw.trim();
+    if (trimmed === "") return "";
+    if (trimmed === "true") return true;
+    if (trimmed === "false") return false;
+    if (trimmed === "null" || trimmed === "~") return null;
+    if (/^-?\d+(\.\d+)?$/.test(trimmed)) return Number(trimmed);
+    if ((trimmed.startsWith('"') && trimmed.endsWith('"')) || (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+      return trimmed.slice(1, -1);
+    }
+    if (trimmed.startsWith("[") && trimmed.endsWith("]")) {
+      const inner = trimmed.slice(1, -1).trim();
+      if (!inner) return [];
+      return inner.split(",").map((s) => parseVal(s.trim()));
+    }
+    return trimmed;
+  }
+
+  for (let i = 0; i < lines.length; i++) {
+    const rawLine = lines[i];
+    let line = rawLine;
+    const commentIdx = line.indexOf("#");
+    if (commentIdx !== -1) {
+      const before = line.slice(0, commentIdx);
+      const singleQuotes = (before.match(/'/g) || []).length;
+      const doubleQuotes = (before.match(/"/g) || []).length;
+      if (singleQuotes % 2 === 0 && doubleQuotes % 2 === 0) {
+        line = before;
+      }
+    }
+    if (!line.trim()) continue;
+
+    const indent = line.search(/\S/);
+    const content = line.trim();
+
+    while (stack.length > 1 && indent <= stack[stack.length - 1].indent) {
+      stack.pop();
+    }
+
+    const current = stack[stack.length - 1];
+
+    if (content.startsWith("- ")) {
+      const itemVal = parseVal(content.slice(2));
+      let targetArray;
+      if (Array.isArray(current.obj)) {
+        targetArray = current.obj;
+      } else if (current.key && current.obj && Array.isArray(current.obj[current.key])) {
+        targetArray = current.obj[current.key];
+      } else if (current.key && current.obj) {
+        current.obj[current.key] = [];
+        targetArray = current.obj[current.key];
+      }
+      if (targetArray) {
+        targetArray.push(itemVal);
+      }
+      continue;
+    }
+
+    const colonIdx = content.indexOf(":");
+    if (colonIdx !== -1) {
+      const key = content.slice(0, colonIdx).trim();
+      const valStr = content.slice(colonIdx + 1).trim();
+
+      if (valStr === "") {
+        let isNextArray = false;
+        for (let j = i + 1; j < lines.length; j++) {
+          const nextTrimmed = lines[j].trim();
+          if (!nextTrimmed || nextTrimmed.startsWith("#")) continue;
+          if (nextTrimmed.startsWith("- ")) isNextArray = true;
+          break;
+        }
+        const container = isNextArray ? [] : {};
+        if (Array.isArray(current.obj)) {
+          current.obj.push({ [key]: container });
+        } else {
+          current.obj[key] = container;
+        }
+        stack.push({ indent, obj: container, key });
+      } else {
+        const val = parseVal(valStr);
+        if (Array.isArray(current.obj)) {
+          current.obj.push({ [key]: val });
+        } else {
+          current.obj[key] = val;
+        }
+        current.key = key;
+      }
+    }
+  }
+
+  return root;
+}
+
+/**
+ * Extracts and parses YAML frontmatter from markdown task files.
+ * Supports standard `--- ... ---` envelopes (including `kind: Task`, `version: agentctl.task/v1`).
+ *
  * @param {string} content
- * @returns {Record<string, any> | null}
+ * @returns {{ metadata: Record<string, any>, body: string, rawFrontmatter: string } | null}
  */
-export function parseEnvelopeHeader(content) {
-  if (!content) return null;
-  const match = String(content).match(/<!--\s*JULES_TASK_ENVELOPE:\s*({[\s\S]*?})\s*-->/);
+export function parseTaskFrontmatter(content) {
+  if (!content || typeof content !== "string") return null;
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)/);
   if (!match) return null;
   try {
-    return JSON.parse(match[1]);
+    const parsed = parseYamlSubset(match[1]);
+    if (!parsed || typeof parsed !== "object" || Object.keys(parsed).length === 0) {
+      return null;
+    }
+    const body = content.slice(match[0].length);
+    return {
+      metadata: parsed,
+      body,
+      rawFrontmatter: match[1],
+    };
   } catch {
     return null;
   }
 }
 
+/**
+ * Serializes task metadata into a canonical `agentctl.task/v1` YAML frontmatter block.
+ *
+ * @param {Record<string, any>} meta
+ * @returns {string}
+ */
+export function serializeTaskFrontmatter(meta = {}) {
+  const lines = [
+    "---",
+    `kind: ${meta.kind || "Task"}`,
+    `version: ${meta.version || "agentctl.task/v1"}`,
+  ];
+  if (meta.id) lines.push(`id: ${meta.id}`);
+  if (meta.title) lines.push(`title: ${meta.title}`);
+  if (meta.role) lines.push(`role: ${meta.role}`);
+  if (meta.tier) lines.push(`tier: ${meta.tier}`);
+  const base = meta.baseCommit || meta.base_commit || meta.baseSha || meta.base_sha;
+  if (base) lines.push(`base_commit: ${base}`);
+
+  if (meta.risk && typeof meta.risk === "object") {
+    lines.push("risk:");
+    if (meta.risk.lane) lines.push(`  lane: ${meta.risk.lane}`);
+    if (meta.risk.require_plan_approval !== undefined) {
+      lines.push(`  require_plan_approval: ${Boolean(meta.risk.require_plan_approval)}`);
+    }
+  }
+
+  const cb = meta.circuitBreaker || meta.circuit_breaker;
+  if (cb && typeof cb === "object") {
+    lines.push("circuitBreaker:");
+    if (cb.max_attempts !== undefined) lines.push(`  max_attempts: ${cb.max_attempts}`);
+    if (cb.max_diff_lines !== undefined) lines.push(`  max_diff_lines: ${cb.max_diff_lines}`);
+    if (cb.stop_if_same_failure_repeats !== undefined) lines.push(`  stop_if_same_failure_repeats: ${cb.stop_if_same_failure_repeats}`);
+  }
+
+  if (Array.isArray(meta.dependsOn) && meta.dependsOn.length > 0) {
+    lines.push("dependsOn:");
+    for (const dep of meta.dependsOn) {
+      lines.push(`  - ${dep}`);
+    }
+  }
+
+  const allowPaths = meta.scope?.allow || meta.allowed_paths || meta.targetFiles || [];
+  const denyPaths = meta.scope?.deny || meta.forbiddenPaths || meta.denyPaths || [];
+
+  lines.push("scope:");
+  lines.push("  allow:");
+  if (Array.isArray(allowPaths) && allowPaths.length > 0) {
+    for (const p of allowPaths) lines.push(`    - ${p}`);
+  }
+  lines.push("  deny:");
+  if (Array.isArray(denyPaths) && denyPaths.length > 0) {
+    for (const p of denyPaths) lines.push(`    - ${p}`);
+  }
+
+  const commands = meta.verification?.commands || (meta.verifyCmd ? [meta.verifyCmd] : []);
+  const requireNonzero = meta.verification?.require_nonzero_test_count;
+  const trustedBase = meta.verification?.trusted_base;
+  if ((Array.isArray(commands) && commands.length > 0) || requireNonzero !== undefined || trustedBase) {
+    lines.push("verification:");
+    if (Array.isArray(commands) && commands.length > 0) {
+      lines.push("  commands:");
+      for (const cmd of commands) lines.push(`    - ${cmd}`);
+    }
+    if (requireNonzero !== undefined) {
+      lines.push(`  require_nonzero_test_count: ${requireNonzero}`);
+    }
+    if (trustedBase) {
+      lines.push(`  trusted_base: ${trustedBase}`);
+    }
+  }
+
+  const invariants = Array.isArray(meta.invariants) ? meta.invariants : (Array.isArray(meta.constraints) ? meta.constraints : []);
+  if (invariants.length > 0) {
+    lines.push("invariants:");
+    for (const inv of invariants) lines.push(`  - ${inv}`);
+  }
+
+  const mcpList = meta.mcp_directives || meta.mcpDirectives;
+  if (Array.isArray(mcpList) && mcpList.length > 0) {
+    lines.push("mcp_directives:");
+    for (const d of mcpList) lines.push(`  - ${d}`);
+  }
+
+  if (meta.flags && typeof meta.flags === "object") {
+    lines.push("flags:");
+    for (const [k, v] of Object.entries(meta.flags)) {
+      lines.push(`  ${k}: ${v}`);
+    }
+  }
+
+  lines.push("---");
+  return lines.join("\n");
+}
+
+/**
+ * Parse metadata payload from either `agentctl.task/v1` frontmatter or HTML comment JULES_TASK_ENVELOPE.
+ *
+ * @param {string} content
+ * @returns {Record<string, any> | null}
+ */
+export function parseEnvelopeHeader(content) {
+  if (!content) return null;
+  const str = String(content);
+
+  // 1. Check for YAML frontmatter (agentctl.task/v1 or standard frontmatter)
+  const frontmatter = parseTaskFrontmatter(str);
+  if (frontmatter && frontmatter.metadata) {
+    const m = frontmatter.metadata;
+    let verifyCmd = m.verifyCmd || m.verify;
+    if (!verifyCmd && m.verification) {
+      if (Array.isArray(m.verification.commands) && m.verification.commands.length > 0) {
+        verifyCmd = m.verification.commands[0];
+      } else if (typeof m.verification.commands === "string") {
+        verifyCmd = m.verification.commands;
+      } else if (typeof m.verification === "string") {
+        verifyCmd = m.verification;
+      }
+    }
+
+    const scope = m.scope || {};
+    const allow = Array.isArray(scope.allow) ? scope.allow : (Array.isArray(m.allowed_paths) ? m.allowed_paths : (Array.isArray(m.targetFiles) ? m.targetFiles : []));
+    const deny = Array.isArray(scope.deny) ? scope.deny : (Array.isArray(m.forbiddenPaths) ? m.forbiddenPaths : (Array.isArray(m.denyPaths) ? m.denyPaths : []));
+
+    const flags = m.flags || {};
+    if (m.autoPr !== undefined) flags.autoPr = Boolean(m.autoPr);
+    if (m.requirePlanApproval !== undefined) flags.requirePlanApproval = Boolean(m.requirePlanApproval);
+    if (m.repoless !== undefined) flags.repoless = Boolean(m.repoless);
+
+    const risk = m.risk && typeof m.risk === "object" ? m.risk : {};
+    const rawLane = risk.lane || m.risk_lane || m.riskLane;
+    const riskLane = rawLane ? String(rawLane).toLowerCase() : (flags.requirePlanApproval ? "amber" : "green");
+    if (risk.require_plan_approval !== undefined) {
+      flags.requirePlanApproval = Boolean(risk.require_plan_approval);
+    } else if (risk.requirePlanApproval !== undefined) {
+      flags.requirePlanApproval = Boolean(risk.requirePlanApproval);
+    } else if (riskLane === "amber" && flags.requirePlanApproval === undefined) {
+      flags.requirePlanApproval = true;
+    }
+
+    const circuitBreaker = m.circuitBreaker || m.circuit_breaker;
+    const invariants = Array.isArray(m.invariants) ? m.invariants : (Array.isArray(m.constraints) ? m.constraints : []);
+    const mcpDirectives = m.mcp_directives || m.mcpDirectives;
+
+    const metaObj = m.metadata && typeof m.metadata === "object" ? m.metadata : {};
+    const taskId = m.id || m.taskId || metaObj.id || metaObj.taskId;
+    const title = m.title || metaObj.title || (typeof m.intent === "string" ? m.intent : m.intent?.outcome);
+
+    let verification = m.verification;
+    if (typeof verification === "string") {
+      verification = { commands: [verification] };
+    } else if (Array.isArray(verification)) {
+      verification = { commands: verification };
+    } else if (verification && typeof verification === "object") {
+      if (typeof verification.commands === "string") {
+        verification = { ...verification, commands: [verification.commands] };
+      }
+    } else if (verifyCmd) {
+      verification = { commands: [verifyCmd] };
+    }
+
+    return {
+      version: m.version || m.apiVersion || 1,
+      kind: m.kind || "Task",
+      id: taskId,
+      taskId,
+      title,
+      intent: m.intent,
+      role: m.role || metaObj.role,
+      tier: m.tier || metaObj.tier,
+      risk: {
+        lane: riskLane,
+        require_plan_approval: Boolean(flags.requirePlanApproval),
+      },
+      circuitBreaker,
+      dependsOn: m.dependsOn,
+      flags,
+      verifyCmd,
+      verification,
+      scope: {
+        allow,
+        deny,
+      },
+      targetFiles: allow,
+      allowed_paths: allow,
+      forbiddenPaths: deny,
+      invariants,
+      constraints: invariants,
+      mcp_directives: Array.isArray(mcpDirectives) ? mcpDirectives : (typeof mcpDirectives === "string" ? [mcpDirectives] : []),
+      baseCommit: m.base_commit || m.base_sha || m.baseCommit || m.baseRef,
+      base_commit: m.base_commit || m.base_sha || m.baseCommit || m.baseRef,
+      promptBody: frontmatter.body,
+    };
+  }
+
+  // 2. Legacy HTML comment fallback
+  const match = str.match(/<!--\s*JULES_TASK_ENVELOPE:\s*({[\s\S]*?})\s*-->/);
+  if (match) {
+    try {
+      return JSON.parse(match[1]);
+    } catch {
+      return null;
+    }
+  }
+
+  return null;
+}
+