jules-orchestrator-kit 0.73.1 → 0.74.0

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.74.0] - 2026-09-19
+
+### Added
+- **Native `agentctl.task/v1` Frontmatter Specification & Zero-Dependency Parser (`src/envelope.mjs`, `scripts/validate-envelope.mjs`)**: Added canonical YAML frontmatter envelope support for task files (`.md`) without third-party dependencies. Reconciles `scope.allow`, `scope.deny`, `verification.commands`, `invariants`, `mcp_directives`, and `flags` with 100% backward compatibility for legacy HTML comments (`<!-- JULES_TASK_ENVELOPE: ... -->`).
+- **Taxonomy Delegation Lanes (Green / Amber / Orange / Red) (`src/envelope.mjs`, `src/wizard-task.mjs`)**: Formulated formal risk lane delegation. Red tasks are rejected at validation; Orange tasks warn for external execution only; Amber tasks allow protected path changes (e.g. dependency upgrades in `package.json`, migrations, auth) under explicit plan approval (`requirePlanApproval: true`). Green tasks prevent unapproved protected scope mutations.
+- **Circuit Breaker & Verification Contract in Envelope (`src/envelope.mjs`)**: Added frontmatter declarations for `circuitBreaker` (`max_attempts`, `max_diff_lines`, `stop_if_same_failure_repeats`) and `verification` metadata (`require_nonzero_test_count`, `trusted_base`), alongside `constraints` alias support.
+- **Stack Invariant & MCP Directive Ingestion (`src/wizard-task.mjs`)**: Automatically infers runtime constraints (Zero-JS for Astro, workerd edge runtime constraints for Cloudflare Wrangler) and injects mandatory pre-execution documentation lookup directives into task instructions.
+- **Dependency Upgrade Scope Harmonization (`src/wizard-task.mjs`)**: Updated `buildGuardrailFooter` to exclude explicitly authorized paths (`opts.allowedPaths`) from forbidden path warnings, eliminating conflicting instructions for dependency upgrade workloads.
+- **Diff Payload Governor Branch Base Comparison (`src/wizard-task.mjs`)**: Calculated diff payload sizes against `git diff origin/${baseBranch}...HEAD | wc -c` instead of local uncommitted diffs.
+
 ## [0.73.1] - 2026-09-17
 
 ### Changed

package/README.md

@@ -12,11 +12,12 @@ Use the kit to describe a scoped coding task, send it to Google Jules or an
 installed Claude Code, Codex or Gemini CLI, and verify the resulting changes.
 You can also run local checks without connecting an agent provider.
 
-**Dispatch and verification are separate.** Dispatch sends the task; `gate` runs
-configured checks on changes. `gate --fix` can request automated repairs. Provider
-output and passing checks still need review before merging.
+**Dispatch, verification and repair are explicit.** Dispatch sends the task;
+`gate` runs configured checks without mutating the working tree. Use
+`agentctl repair` explicitly for repair workflows. Provider output and passing
+checks still need review before merging.
 
-The current release is **v0.73.1**, a pre-1.0 release. A long-term stability policy is a
+The current release is **v0.74.0**, a pre-1.0 release. A long-term stability policy is a
 [v1.0 goal](https://github.com/FullThrottle83/jules-orchestrator-kit/blob/main/ROADMAP_V1.md).
 
 ## Quickstart
@@ -32,9 +33,16 @@ npx jules-orchestrator-kit init
 ```
 
 The wizard detects the project and asks about provider and verification settings.
-Use `init --yes` to accept defaults. It creates `.agent/config.yml`, agent
-instructions, role prompts and project contract files. Inspect the generated
-configuration and diff, especially the test command and protected paths.
+Use `init --yes` to accept defaults. By default it writes only the canonical
+`.agent/config.yml` plus runtime-state entries in `.gitignore` when they are
+missing. Inspect the generated configuration and diff, especially the test
+command and protected paths. Use `init --dry-run` to preview the exact writes
+without changing the repository.
+
+The historical full scaffold (AGENTS.md, specialist prompts, rules, workflows and
+contract templates) remains available through `agentctl init --force` and the
+legacy `jules-init` entry point during the 0.x migration window; it is no longer
+default-owned by `agentctl init`.
 
 ```bash
 git diff
@@ -43,9 +51,9 @@ git status --short
 
 Stage the generated files you reviewed, then commit them. The committed
 configuration establishes the trusted base policy used by verification. On an
-already initialized repository, back up and review `.agent/config.yml` and
-`.agent/jules.yml` before rerunning `init`; the wizard can regenerate those
-manifests. Avoid `--force` unless replacement of generated files is intended.
+already initialized repository, back up and review `.agent/config.yml` before
+rerunning `init`. Existing legacy `.agent/jules.yml` files are left untouched
+by the default path. `--force` deliberately opts back into the legacy full scaffold.
 
 ### 2. Check provider readiness
 
@@ -107,7 +115,7 @@ For direct `agentctl` commands, install globally with
 | Create a scoped task | `agentctl task create` |
 | Preview queued work | `agentctl queue --dry-run` |
 | Check changes locally | `agentctl gate` |
-| Verify and request repairs | `agentctl gate --fix` |
+| Start an explicit repair workflow | `agentctl repair --input "<failure>" --task` |
 | Diagnose setup | `agentctl doctor` |
 | Inspect a command's flags | `agentctl help <command>` |
 
@@ -166,7 +174,7 @@ npm run package-integrity
 npm run guard-reach
 ```
 
-The recorded baseline is **1530 unit tests across 204 suites**. Doc-sync compares
+The recorded baseline is **1553 unit tests across 204 suites**. Doc-sync compares
 that count with an actual run. Counts do not establish correctness for every
 provider or project. See
 [contributing](https://github.com/FullThrottle83/jules-orchestrator-kit/blob/main/CONTRIBUTING.md)
@@ -186,19 +194,12 @@ for the review process.
 First identify which files setup created and which files already belonged to your
 project. For shared files, remove only the kit's additions using Git history.
 
-For a repository where **all listed paths belong exclusively to the kit**, remove
-the tracked scaffold and runtime state as follows. Adapt this list first if any
-path contains your own instructions, configuration or queued work:
-
-```bash
-git rm -rf --ignore-unmatch .agent AGENTS.md SPEC.md CONSTRAINTS.md DESIGN.md \
-  .github/workflows/agent-gate.yml .gitlab-ci.agent-gate.yml .cursor/rules/jules.mdc
-rm -rf .agent .agentctl
-npm uninstall -g jules-orchestrator-kit
-```
+For the default minimal setup, remove `.agent/config.yml` and the kit's
+runtime-state block from `.gitignore`. Repositories that previously used the
+legacy full scaffold may also contain AGENTS.md, prompts, rules, workflows and
+contract files; remove those only after confirming ownership.
 
-Remove the kit's appended `.gitignore` block while preserving other entries.
-See the uninstall guide for the complete inventory.
+See the uninstall guide for the complete inventory and legacy cleanup steps.
 
 ## Limitations and attribution
 

package/bin/agentctl.mjs

@@ -2,7 +2,7 @@
 
 import { parseArgs } from "node:util";
 import { readFileSync, existsSync, readdirSync, statSync, renameSync, mkdirSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { join, resolve, relative } from "node:path";
 import { applyEnvAliases } from "../src/env-aliases.mjs";
 import { selectFailureOutput } from "../src/ops/verify-output.mjs";
 import { loadConfig, resolveRoot, detectStack, bootstrapZeroTestRepo } from "../src/config.mjs";
@@ -22,7 +22,18 @@ import { COMMAND_REGISTRY } from "../src/ops/command-registry.mjs";
 applyEnvAliases(process.env);
 
 const args = process.argv.slice(2);
-const command = args[0];
+const requestedCommand = args[0] || "";
+const gateCommands = new Set(["gate", "check", "audit"]);
+
+if (gateCommands.has(requestedCommand) && args.includes("--fix")) {
+  console.error("Error: `agentctl gate` is non-mutating; `--fix` no longer dispatches automated repairs.");
+  console.error("Run the gate normally, then use `agentctl repair` explicitly with the failure trace you want repaired.");
+  process.exit(2);
+}
+
+// `repair` is the canonical spelling; `fix` remains a 0.x compatibility
+// alias. Both route through the same existing implementation below.
+const command = requestedCommand;
 
 export const VERSION = KIT_VERSION;
 
@@ -294,8 +305,13 @@ async function main() {
   }
 
   const root = resolveRoot();
-  reapOrphanedIntents(root);
-  reapStaleMutexDirs(root);
+  // Init is a configuration boundary, not an operational maintenance command.
+  // In particular, --dry-run must not create .agent/ indirectly by reaping
+  // journal intents or mutex directories before init itself gets control.
+  if (command !== "init") {
+    reapOrphanedIntents(root);
+    reapStaleMutexDirs(root);
+  }
   const config = loadConfig(root);
 
   switch (command) {
@@ -361,7 +377,7 @@ async function main() {
           console.error(
             `Error: Unknown agent role '${values.role}'. Expected matching prompt file in .agent/prompts/ (e.g. Auditor, Performance, Security, Hygiene, Testing).`
           );
-          console.error(`   Run 'agentctl init' to scaffold the shipped role prompts.`);
+          console.error(`   Use a canonical shipped role name or add a repository override under .agent/prompts/.`);
           process.exit(1);
         }
       }
@@ -676,7 +692,7 @@ async function main() {
           } else if (failedPhase === "verify" || failedPhase === "evidence") {
             console.log(`💡 Remediation Hint (Exit ${res.code} Verification Failed):`);
             console.log(`   • The stage above exited non-zero. Reproduce it locally, then re-run the gate.`);
-            console.log(`   • To let agentctl attempt the repair loop itself, pass: agentctl gate --fix\n`);
+            console.log(`   • To start an explicit repair workflow, pipe the failing command's output to: agentctl repair\n`);
           } else if (res.code === 3) {
             // The same violation has two very different causes. Right after
             // `init`, every offending path is a file the tool itself just wrote
@@ -965,6 +981,7 @@ async function main() {
       break;
     }
 
+    case "repair":
     case "fix": {
       const { repair, planTaskCreate, resolveRoot, redactSecrets } = await import("../index.mjs");
       const { values, positionals } = parseArgs({
@@ -996,7 +1013,7 @@ async function main() {
       }
 
       if (!errorInput.trim()) {
-        console.error("❌ Error: No error log or failure input provided. Pipe stdout/stderr via `npm test 2>&1 | agentctl fix` or provide --file/--input.");
+        console.error("❌ Error: No error log or failure input provided. Pipe stdout/stderr via `npm test 2>&1 | agentctl repair` or provide --file/--input.");
         process.exit(1);
       }
 
@@ -1957,19 +1974,54 @@ async function main() {
         provider: values.provider,
         profile: values.profile,
         allowDefaults: true,
+        dryRun: values["dry-run"],
+        // --force is retained as the explicit 0.x compatibility path: it
+        // restores the legacy Jules manifest and full repository scaffold.
+        legacyManifest: values.force,
+        // JSON mode is a protocol surface: progress spinners must not prefix
+        // the payload with human-readable status lines.
+        stdout: values.json ? { write() {} } : process.stdout,
       });
 
-      // The wizard writes the manifest; the assets the CLI's documented
-      // features actually need — AGENTS.md, the role prompts, the guardrails,
-      // the gitignore entries — used to be scaffolded only by the separate
-      // `jules-init` binary that the README's quickstart never mentions.
-      const { scaffoldRepoAssets } = await import("../src/scaffold.mjs");
-      const scaffold = scaffoldRepoAssets(root, { force: values.force });
+      // Default init deliberately owns only the canonical config plus the
+      // runtime-state ignore block. The old full scaffold is opt-in via
+      // --force (and remains available through the shipped jules-init binary).
+      const {
+        ensureGitignore,
+        planGitignoreEntries,
+        planScaffoldRepoAssets,
+        scaffoldRepoAssets,
+      } = await import("../src/scaffold.mjs");
+      const plannedGitignore = planGitignoreEntries(root);
+      const legacyPlan = values.force ? planScaffoldRepoAssets(root, { force: true }) : { created: [], gitignore: plannedGitignore };
+      const scaffold =
+        values.force && !values["dry-run"]
+          ? scaffoldRepoAssets(root, { force: true })
+          : { created: legacyPlan.created, gitignore: plannedGitignore };
+      const gitignore =
+        values["dry-run"]
+          ? plannedGitignore
+          : values.force
+            ? scaffold.gitignore
+            : ensureGitignore(root);
+      const writes = [
+        ...res.writes.map((p) => (relative(root, p) || p).replaceAll("\\", "/")),
+        ...legacyPlan.created,
+        ...(plannedGitignore.length > 0 ? [".gitignore"] : []),
+      ].filter((p, index, all) => all.indexOf(p) === index);
 
       if (values.json) {
-        console.log(JSON.stringify({ ...res, scaffold }, null, 2));
+        console.log(JSON.stringify({ ...res, writes, gitignore }, null, 2));
       } else {
-        console.log(`✅ Onboarding complete! Manifest generated at ${res.configPath}`);
+        console.log(
+          values["dry-run"]
+            ? "🧪 Dry run — no files written."
+            : `✅ Onboarding complete! Manifest generated at ${res.configPath}`
+        );
+        if (values["dry-run"]) {
+          console.log("   Would write:");
+          for (const path of writes) console.log(`     - ${path}`);
+        }
         console.log(`   Tier: ${res.plan.tier.toUpperCase()} (${res.plan.limits.concurrency} worker(s), ${res.plan.limits.daily_tasks} daily tasks)`);
         {
           const { probeProvider } = await import("../src/provider-readiness.mjs");
@@ -1988,34 +2040,35 @@ async function main() {
           console.log(`   Verification Test Command : None detected (run "agentctl bootstrap" to create a test oracle)`);
         }
         console.log(`   Active Presets            : ${res.plan.presets.join(", ")}`);
-        for (const item of scaffold.created) {
-          console.log(`   Scaffolded                : ${item}`);
-        }
-        if (scaffold.gitignore.length > 0) {
-          console.log(`   Ignored runtime state     : ${scaffold.gitignore.length} entries added to .gitignore`);
-        }
-
-        // `.agent/config.yml` and `.agent/jules.yml` are both on the gate's deny
-        // list, by design — the agent must not edit its own rules. Leaving them
-        // uncommitted meant the very first `agentctl gate` rejected the working
-        // tree for files init had just written, which reads as the tool
-        // catching the user cheating on step three.
-        const rootContracts = ["SPEC.md", "CONSTRAINTS.md", "DESIGN.md"].filter((f) => existsSync(join(root, f)));
-        // A fresh `npm install`/`npm init -y` just created package manifests the
-        // scope rules `protect`. Leaving them out of the hint meant the very
-        // first `agentctl gate`/`agentctl task create` still rejected the tree
-        // even after the user committed exactly what this message listed. Fold
-        // the install-produced, currently-addable artifacts in so the suggested
-        // commit actually leaves the tree clean enough for step three.
-        const { addableOnboardingArtifacts } = await import("../src/git.mjs");
-        const filesToAdd = [".agent", "AGENTS.md", ...rootContracts, ...addableOnboardingArtifacts(root), ".gitignore"]
-          .filter((f) => existsSync(join(root, f)));
-        console.log(`\n   Commit the manifest and contracts so the gate does not read them as agent edits:`);
-        console.log(`     git add ${filesToAdd.join(" ")} && git commit -m "chore: add agent config"`);
-
-        const { resolveNextStep, renderNextStep } = await import("../src/ops/next-step.mjs");
-        const next = resolveNextStep(root);
-        console.log(renderNextStep({ version: VERSION, root, next, budgetLine: "" }));
+        if (values.force) {
+          const verb = values["dry-run"] ? "Would scaffold (legacy)" : "Scaffolded (legacy)";
+          for (const item of legacyPlan.created) {
+            console.log(`   ${verb.padEnd(26)}: ${item}`);
+          }
+        }
+        if (!values["dry-run"] && gitignore.length > 0) {
+          console.log(`   Ignored runtime state     : ${gitignore.length} entries added to .gitignore`);
+        }
+
+        if (!values["dry-run"]) {
+          // A fresh `npm install`/`npm init -y` may have created package
+          // manifests the scope rules protect. Include only files that really
+          // exist; minimal init itself owns .agent/config.yml and, when needed,
+          // the .gitignore runtime-state block.
+          const { addableOnboardingArtifacts } = await import("../src/git.mjs");
+          const filesToAdd = [
+            ".agent/config.yml",
+            ...(values.force ? [".agent/jules.yml", ...legacyPlan.created] : []),
+            ...addableOnboardingArtifacts(root),
+            ".gitignore",
+          ].filter((p, index, all) => all.indexOf(p) === index && existsSync(join(root, p)));
+          console.log(`\n   Commit the config so the gate does not read it as an agent edit:`);
+          console.log(`     git add ${filesToAdd.join(" ")} && git commit -m "chore: add agent config"`);
+
+          const { resolveNextStep, renderNextStep } = await import("../src/ops/next-step.mjs");
+          const next = resolveNextStep(root);
+          console.log(renderNextStep({ version: VERSION, root, next, budgetLine: "" }));
+        }
       }
       process.exit(0);
       break;

package/bin/init.js

@@ -40,12 +40,14 @@ try {
 
 if (isHelp) {
   console.log(`
-Google Jules Orchestration Kit - Init Scaffolding CLI
+Google Jules Orchestration Kit - Legacy Full Scaffold
 
 Usage:
-  npx jules-orchestrator-kit [options]
   npx jules-init [options]
 
+For the minimal canonical setup, use:
+  npx jules-orchestrator-kit init
+
 Options:
   -f, --force          Overwrite existing AGENTS.md, .agent/jules.yml, and orchestration scripts.
   -i, --interactive    Launch interactive wizard to prompt for repository and branch configuration.
@@ -119,10 +121,9 @@ if (detected.testCmd || detected.buildCmd) {
   console.log(`   - Build Command: ${detected.buildCmd || "(none)"}`);
 }
 
-// 2-3. Scaffold AGENTS.md, .agent/ structure, role prompts, rules and workflows.
-// Shared with `agentctl init` so the two entry points cannot scaffold different
-// repositories — which is exactly what they used to do, with the README's
-// quickstart pointing at the one that scaffolded less.
+// 2-3. Legacy full scaffold: AGENTS.md, .agent/ role prompts, rules and
+// workflows. The canonical `agentctl init` path is intentionally smaller now;
+// this entry point remains for 0.x repositories that still want the full bundle.
 const { scaffoldRepoAssets } = await import("../src/scaffold.mjs");
 const scaffolded = scaffoldRepoAssets(targetDir, { force: isForce });
 for (const item of scaffolded.created) {
@@ -133,11 +134,8 @@ const agentDir = path.join(targetDir, ".agent");
 
 // Scaffold the manifest pair.
 //
-// This entry point used to hand-roll a thinner `.agent/jules.yml` while
-// `agentctl init` wrote a `.agent/config.yml` the runtime actually reads, so
-// which of the two scaffolders you happened to run decided whether the
-// repository had a provider, a tier and a verification profile at all. Both
-// now go through `planInit`.
+// This compatibility entry point still writes both manifests, but derives them
+// from the same `planInit` model as the canonical path so values cannot drift.
 const { planInit } = await import("../src/wizard-init.mjs");
 const initPlan = planInit(targetDir, {
   testCmd: detected.testCmd,
@@ -226,8 +224,7 @@ if (fs.existsSync(targetPkgPath) && targetDir !== kitRoot) {
   }
 }
 
-// 5b. The .gitignore entries are written by scaffoldRepoAssets above, so the
-// two entry points cannot disagree about which runtime paths stay untracked.
+// 5b. Reuse the same runtime ignore policy as canonical init.
 if (scaffolded.gitignore.length > 0) {
   console.log(`✅ Added ${scaffolded.gitignore.length} runtime state entries to .gitignore`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jules-orchestrator-kit",
-  "version": "0.73.1",
+  "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",

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);