jules-orchestrator-kit 0.2.8 → 0.3.0

package/JULES_RULES_TEMPLATE.md

@@ -36,12 +36,12 @@ Dispatch tasks to Jules when ALL of the following apply:
 
 Jules automatically infers test and build verification commands via `scripts/command-resolver.mjs`:
 - `.agent/jules.yml` -> Custom user commands (`test_cmd`, `build_cmd`)
-- `package.json` -> `npm test` (or `npm run lint && npm test` if lint script exists)
-- `Cargo.toml` -> `cargo test --workspace && cargo build`
-- `go.mod` -> `go test ./... && go build ./...`
-- `pyproject.toml` -> `pytest`
-- `pom.xml` -> `mvn test`
-- `build.gradle` -> `./gradlew test`
+- `package.json` -> `testCmd: "npm test"` (or `"npm run lint && npm test"`), `buildCmd: "npm run build"`
+- `Cargo.toml` -> `testCmd: "cargo test --workspace"`, `buildCmd: "cargo build"`
+- `go.mod` -> `testCmd: "go test ./..."`, `buildCmd: "go build ./..."`
+- `pyproject.toml` -> `testCmd: "pytest"`, `buildCmd: ""`
+- `pom.xml` -> `testCmd: "mvn test"`, `buildCmd: "mvn compile"`
+- `build.gradle` -> `testCmd: "./gradlew test"`, `buildCmd: "./gradlew assemble"`
 - Workspace graphs (`turbo.json`, `pnpm-workspace.yaml`, `nx.json`) -> targeted affected package filters
 
 ---

package/README.md

@@ -54,8 +54,7 @@ Instead of blindly trusting AI code mutations, the Orchestrator acts as a strict
 2. **Secret & Path Defense:** Hides passwords, API keys (`entropy > 3.6`), and blocks path traversal (`../`).
 3. **Jules Proposes Code:** Google Jules mutates code in an isolated environment.
 4. **Tiered Verification:** Enforces scope bounds (`git diff`), runs fast-fail linters/type-checks, then executes full test/build suites.
-5. **Self-Correction (OODA Loop):** If tests fail, stderr traces are fed back to Jules to self-correct (up to 4 attempts).
-6. **Clean Pull Request:** Once verified green, commits & pushes clean code to GitHub.
+5. **Self-Healing PR Gatekeeper (OODA Feedback):** Parses execution stderr traces, logs diagnostic telemetry to `.agent/history/metrics.jsonl`, and enforces strict exit code 1 to block bad code from merging.
 
 <details>
 <summary><b>🔍 View System Architecture Diagram (For Power Users)</b></summary>
@@ -75,33 +74,22 @@ sequenceDiagram
     Orc->>Git: Provision Worktree (`git worktree add`)
     Orc->>Jules: Dispatch Context, Invariants & Target Scope
 
-    loop Max Retries (Attempts < 4)
-        Jules->>Git: Propose Code Mutations
-        
-        note over Orc,Git: Phase 2: Tiered Verification
-        Orc->>Git: Scope Audit (`git diff --name-only` vs forbidden_paths)
-        alt Scope Breach
-            Git-->>Orc: Scope Violation Error
-        else Scope OK
-            Orc->>Git: Run Fast-Fail Checks (Lint / Typecheck)
-            opt Pass Static Checks
-                Orc->>Git: Run Heavy Suite (`build_cmd` & `test_cmd`)
-            end
-        end
-
-        alt Verification Gates Pass
-            Orc->>Git: Commit, Push & Cleanup Worktree
-            Orc->>CLI: Return Success + Metrics (.agent/history/metrics.jsonl)
-            note over Jules,Git: Exit Loop
-        else Verification Gates Fail (Attempts < 4)
-            Git-->>Orc: Execution Trace (stdout/stderr / Diff)
-            Orc->>Jules: Inject OODA Feedback & Error Context
-        end
+    Jules->>Git: Propose Code Mutations
+    
+    note over Orc,Git: Phase 2: Tiered Verification Gatekeeper
+    Orc->>Git: Scope Audit (`git diff -z --name-only` vs forbidden_paths)
+    alt Scope Breach
+        Git-->>Orc: Scope Violation Error (Exit 1)
+    else Scope OK
+        Orc->>Git: Run Verification Suite (`test_cmd` & `build_cmd`)
     end
 
-    opt Verification Gates Fail (Attempts >= 4)
-        Orc->>Git: Abort & Rollback Worktree (`git worktree remove --force`)
-        Orc->>CLI: Return Terminal Failure (.agent/history/errors.jsonl)
+    alt Verification Gates Pass
+        Orc->>Git: Commit, Push & Log Telemetry (.agent/history/metrics.jsonl)
+        Orc->>CLI: Return Success (Exit 0)
+    else Verification Gates Fail
+        Git-->>Orc: Execution Trace (stdout/stderr / Diff)
+        Orc->>CLI: Log OODA Diagnostic Telemetry & Block PR (Exit 1)
     end
 ```
 
@@ -151,28 +139,29 @@ allow_paths: []
 
 > 🛡️ **Zero-Trust Security Model**: `allow_paths` and `forbidden_paths` rules are read **strictly from the target base branch** (`origin/main`), never from untrusted PR branches. Even if an AI agent hallucinates and tries to modify its own security rules in a PR branch, the Orchestrator enforces the immutable rules defined on `main`.
 > ℹ️ Setting `build_cmd: ""` explicitly skips the build verification step (useful for pure test suites or scripts). Note that `.agent/jules.yml` uses a zero-dependency parser that supports flow (`[...]`) and block (`- item`) list subsets.
+> 📦 `.github/` is intentionally included in `package.json`'s `files` array so that `npx jules-init` can automatically scaffold `.github/workflows/jules-audit.yml` into target repositories.
 
 ---
 
 <details>
 <summary><b>🛠️ Supported Language Manifests & Workspace Graphs (15+ Tech Stacks)</b></summary>
 
-| Stack / Ecosystem | Manifest / Workspace File | Default Verification Command |
-|---|---|---|
-| **Turborepo** | `turbo.json` | `npx turbo run test --filter=<pkg>...` |
-| **pnpm Workspace** | `pnpm-workspace.yaml` | `pnpm --filter=...<pkg> test` |
-| **Nx Workspace** | `nx.json` | `npx nx run-many -t test -p <pkg> --with-deps` |
-| **Bun** | `bunfig.toml` / `bun.lockb` | `bun test && bun run build` |
-| **Deno** | `deno.json` / `deno.jsonc` | `deno test && deno task build` |
-| **JavaScript / TypeScript** | `package.json` | `npm run lint && npm test` (or `npm run check:all`) |
-| **Rust** | `Cargo.toml` | `cargo test -p <pkg>` / `cargo test --workspace` |
-| **Go** | `go.mod` | `go test ./... && go build ./...` |
-| **Python** | `pyproject.toml` / `requirements.txt` | `pytest` |
-| **Elixir** | `mix.exs` | `mix test && mix compile` |
-| **Ruby** | `Gemfile` | `bundle exec rake test` |
-| **Swift** | `Package.swift` | `swift test && swift build` |
-| **Java (Maven/Gradle)** | `pom.xml` / `build.gradle` | `mvn test` / `./gradlew test` |
-| **C / C++** | `Makefile` | `make test && make build` |
+| Stack / Ecosystem | Manifest / Workspace File | Test Command (`testCmd`) | Build Command (`buildCmd`) |
+|---|---|---|---|
+| **Turborepo** | `turbo.json` | `npx turbo run test --filter=<pkg>...` | `npx turbo run build --filter=<pkg>...` |
+| **pnpm Workspace** | `pnpm-workspace.yaml` | `pnpm --filter=...<pkg> test` | `pnpm --filter=...<pkg> build` |
+| **Nx Workspace** | `nx.json` | `npx nx run-many -t test -p <pkg> --with-deps` | `npx nx run-many -t build -p <pkg> --with-deps` |
+| **Bun** | `bunfig.toml` / `bun.lockb` | `bun test` | `bun run build` |
+| **Deno** | `deno.json` / `deno.jsonc` | `deno test` | `deno task build` |
+| **JavaScript / TypeScript** | `package.json` | `npm run lint && npm test` | `npm run build` |
+| **Rust** | `Cargo.toml` | `cargo test --workspace` | `cargo build` |
+| **Go** | `go.mod` | `go test ./...` | `go build ./...` |
+| **Python** | `pyproject.toml` / `requirements.txt` | `pytest` | *(none)* |
+| **Elixir** | `mix.exs` | `mix test` | `mix compile` |
+| **Ruby** | `Gemfile` | `bundle exec rake test` | *(none)* |
+| **Swift** | `Package.swift` | `swift test` | `swift build` |
+| **Java (Maven/Gradle)** | `pom.xml` / `build.gradle` | `mvn test` / `./gradlew test` | `mvn compile` / `./gradlew assemble` |
+| **C / C++** | `Makefile` | `make test` | `make build` |
 
 </details>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jules-orchestrator-kit",
-  "version": "0.2.8",
+  "version": "0.3.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/FullThrottle83/jules-orchestrator-kit.git"
@@ -17,7 +17,10 @@
   "files": [
     "bin/",
     "scripts/",
-    ".agent/",
+    ".agent/jules.yml",
+    ".agent/rules/",
+    ".agent/workflows/",
+    ".agent/jules-queue/README.md",
     ".github/",
     ".env.example",
     "JULES_RULES_TEMPLATE.md",

package/scripts/jules-dispatch.mjs

@@ -28,7 +28,7 @@ function loadEnv() {
       if (!trimmed || trimmed.startsWith("#")) continue;
       const eqIdx = trimmed.indexOf("=");
       if (eqIdx > 0) {
-        const key = trimmed.slice(0, eqIdx).trim();
+        const key = trimmed.slice(0, eqIdx).trim().replace(/^export\s+/, "");
         let val = trimmed.slice(eqIdx + 1).trim();
         if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
           val = val.slice(1, -1);
@@ -162,9 +162,23 @@ const repo = process.env.JULES_REPO || "";
 
 if (isMainModule) {
   const possiblePath = path.resolve(process.cwd(), taskPromptArg);
-  if (fs.existsSync(possiblePath) && fs.statSync(possiblePath).isFile()) {
-    assertPathWithinWorkspace(possiblePath);
-    rawPrompt = fs.readFileSync(possiblePath, "utf-8");
+  if (fs.existsSync(possiblePath)) {
+    try {
+      const verifiedPath = assertPathWithinWorkspace(possiblePath);
+      const fd = fs.openSync(verifiedPath, "r");
+      try {
+        const stat = fs.fstatSync(fd);
+        if (stat.isFile()) {
+          rawPrompt = fs.readFileSync(fd, "utf-8");
+        } else {
+          rawPrompt = taskPromptArg;
+        }
+      } finally {
+        fs.closeSync(fd);
+      }
+    } catch (_) {
+      rawPrompt = taskPromptArg;
+    }
   } else {
     rawPrompt = taskPromptArg;
   }
@@ -210,7 +224,9 @@ function cleanupTmp() {
     if (fs.existsSync(tmpDir)) {
       fs.rmSync(tmpDir, { recursive: true, force: true });
     }
-  } catch (_) {}
+  } catch (err) {
+    console.warn(`⚠️ Failed to remove temporary payload directory at ${tmpDir}:`, err.message);
+  }
 }
 
 async function executeDispatch() {

package/scripts/jules-nightly.mjs

@@ -110,7 +110,13 @@ function main() {
   }
 
   logNightlyHistory(results, isDryRun);
-  console.log("\n✅ Nightly Jules audit suite execution completed cleanly.");
+  const hasFailures = results.some((r) => r.status && (r.status.includes("Failed") || r.status.includes("error")));
+  if (hasFailures) {
+    console.error("\n❌ Nightly Jules audit suite completed with task errors.");
+    process.exitCode = 1;
+  } else {
+    console.log("\n✅ Nightly Jules audit suite execution completed cleanly.");
+  }
 }
 
 main();

package/scripts/jules-queue-runner.mjs

@@ -11,6 +11,8 @@ const queueDir = path.resolve(process.cwd(), ".agent/jules-queue");
 const completedDir = path.resolve(process.cwd(), ".agent/jules-queue/completed");
 const queueLogFile = path.join(queueDir, "queue.jsonl");
 
+const processingDir = path.resolve(process.cwd(), ".agent/jules-queue/.processing");
+
 if (!fs.existsSync(queueDir)) {
   console.error(`❌ Queue directory not found: ${queueDir}`);
   process.exit(1);
@@ -20,6 +22,10 @@ if (!fs.existsSync(completedDir)) {
   fs.mkdirSync(completedDir, { recursive: true });
 }
 
+if (!fs.existsSync(processingDir)) {
+  fs.mkdirSync(processingDir, { recursive: true });
+}
+
 function logQueueState(file, status, error = null) {
   const entry = JSON.stringify({
     timestamp: new Date().toISOString(),
@@ -43,6 +49,16 @@ console.log(`🐝 Found ${files.length} tasks in the queue. Processing...`);
 
 files.forEach((file, index) => {
   const filePath = path.join(queueDir, file);
+  const processingPath = path.join(processingDir, file);
+  
+  // Atomic claim: move from queueDir to processingDir before dispatching
+  try {
+    fs.renameSync(filePath, processingPath);
+  } catch (claimErr) {
+    // Another runner already claimed this task file
+    return;
+  }
+
   // Generate title from filename (e.g. "TASK-001-auth-spec.md" -> "TASK 001 auth spec")
   const title = file.replace(/\.md$/, "").replace(/-/g, " ");
   
@@ -51,13 +67,13 @@ files.forEach((file, index) => {
   logQueueState(file, "RUNNING");
   
   try {
-    execFileSync("node", [dispatchScript, title, filePath], {
+    execFileSync("node", [dispatchScript, title, processingPath], {
       stdio: "inherit",
     });
     
     // Move to completed
     const destPath = path.join(completedDir, file);
-    fs.renameSync(filePath, destPath);
+    fs.renameSync(processingPath, destPath);
     logQueueState(file, "COMPLETED");
     console.log(`✅ Moved ${file} to completed/`);
   } catch (error) {

package/scripts/jules-self-audit.mjs

@@ -17,7 +17,9 @@ function runCommand(cmd, ignoreError = false) {
 
 export function matchGlob(filepath, globPattern) {
   const cleanPath = filepath.replace(/\\/g, "/").replace(/^\.\//, "");
-  const segments = globPattern.split("/");
+  // Normalize consecutive glob wildcards (e.g., "**/**" -> "**")
+  const normalizedGlob = globPattern.replace(/\\/g, "/").replace(/(?:\*\*\/)+/g, "**/");
+  const segments = normalizedGlob.split("/");
   const regexParts = [];
   for (let i = 0; i < segments.length; i++) {
     const seg = segments[i];
@@ -33,12 +35,14 @@ export function matchGlob(filepath, globPattern) {
     }
   }
   let patternStr = regexParts.join("/");
-  patternStr = patternStr.replace(/(^|\/)\*\*(\/|$)/g, (m, p1, p2) => {
-    if (p1 === "/" && p2 === "/") return "(?:/|/.*/)";
-    if (p1 === "/") return "(?:/.*)?";
-    if (p2 === "/") return "(?:.*/)?";
+  patternStr = patternStr.replace(/(?:^|\/)\*\*(?:\/|$)/g, (m) => {
+    if (m === "**") return ".*";
+    if (m === "/**/") return "(?:/|/.*/)";
+    if (m === "/**") return "(?:/.*)?";
+    if (m === "**/") return "(?:.*/)?";
     return ".*";
   });
+  patternStr = patternStr.replace(/\*\*/g, ".*");
   return new RegExp(`^${patternStr}$`, "i").test(cleanPath);
 }
 
@@ -166,9 +170,9 @@ export function runSelfAudit() {
 
   console.log(`🔗 Merge-Base Hash: ${mergeBase}`);
 
-  const rawDiffFiles = runCommand(`git diff --name-only ${mergeBase}...HEAD`)
-    .split("\n")
-    .map((f) => f.trim())
+  const rawDiffFiles = runCommand(`git diff -z --name-only ${mergeBase}...HEAD`)
+    .split("\0")
+    .map((f) => f.trim().replace(/^["']|["']$/g, ""))
     .filter(Boolean);
 
   const isBloatFile = (file) => /(\.lock|package-lock\.json|yarn\.lock|pnpm-lock\.yaml|\.png|\.jpg|\.jpeg|\.pdf|\.min\.js|\.map)$/i.test(file);

package/scripts/jules-swarm.mjs

@@ -38,31 +38,70 @@ process.env.JULES_PROJECT_ROOT = process.cwd();
 
 console.log(`🐝 Launching Jules Swarm Orchestrator (${tasks.length} tasks, Concurrency: ${MAX_CONCURRENT}, Worktrees: ${USE_WORKTREES ? "ENABLED" : "DISABLED"})...`);
 
-const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const activeWorktrees = new Set();
+
+function cleanupAllWorktreesSync() {
+  for (const item of Array.from(activeWorktrees)) {
+    if (item.wtDir && fs.existsSync(item.wtDir)) {
+      try {
+        fs.chmodSync(item.wtDir, 0o755);
+      } catch (_) {}
+    }
+    try {
+      execFileSync("git", ["worktree", "remove", "--force", item.wtDir], { stdio: "ignore" });
+    } catch (_) {}
+    if (item.branchName) {
+      try {
+        execFileSync("git", ["branch", "-D", item.branchName], { stdio: "ignore" });
+      } catch (_) {}
+    }
+  }
+  activeWorktrees.clear();
+}
+
+process.on("SIGINT", () => {
+  console.warn("\n⚠️ SIGINT received. Cleaning up active Git worktrees...");
+  cleanupAllWorktreesSync();
+  process.exit(130);
+});
+
+process.on("SIGTERM", () => {
+  console.warn("\n⚠️ SIGTERM received. Cleaning up active Git worktrees...");
+  cleanupAllWorktreesSync();
+  process.exit(143);
+});
 
 async function createWorktree(taskId) {
   const slug = taskId.toLowerCase().replace(/[^a-z0-9]+/g, "-");
   const wtDir = path.resolve(process.cwd(), `.agent/worktrees/${slug}`);
   const branchName = `jules/${slug}`;
+  let item = null;
   try {
     if (!fs.existsSync(path.dirname(wtDir))) {
       fs.mkdirSync(path.dirname(wtDir), { recursive: true });
     }
     await execFileAsync("git", ["worktree", "add", "-b", branchName, wtDir, "HEAD"]);
-    return { wtDir, branchName };
+    item = { wtDir, branchName };
   } catch (err) {
     try {
       await execFileAsync("git", ["worktree", "add", "--force", wtDir, "HEAD"]);
-      return { wtDir, branchName: null };
+      item = { wtDir, branchName: null };
     } catch (fallbackErr) {
       console.warn(`⚠️ Failed to create worktree for ${taskId}:`, fallbackErr.message);
       return null;
     }
   }
+  if (item) activeWorktrees.add(item);
+  return item;
 }
 
 async function removeWorktree(wtDir, branchName) {
   if (!wtDir) return;
+  for (const item of Array.from(activeWorktrees)) {
+    if (item.wtDir === wtDir) {
+      activeWorktrees.delete(item);
+    }
+  }
   try {
     await execFileAsync("git", ["worktree", "remove", "--force", wtDir]);
   } catch (err) {

package/.agent/history/2026-07-27-dispatch-test-swarm-task.md

@@ -1,9 +0,0 @@
----
-type: jules_dispatch
-title: "Test Swarm Task"
-timestamp: "2026-07-27T09:25:41.107Z"
----
-# Jules Task Dispatch: Test Swarm Task
-
-## Prompt
-Test Prompt Description