jules-orchestrator-kit 0.1.0

package/JULES_RULES_TEMPLATE.md

@@ -0,0 +1,52 @@
+# Google Jules Autonomous Worker Directives
+
+These guidelines govern all automated coding tasks executed by Google Jules (`jules`).
+
+---
+
+## 1. Triage Directive (When to use Jules)
+
+Dispatch tasks to Jules when ALL of the following apply:
+1. Scoped code change with a clear objective.
+2. Mechanically verifiable via automated test/build commands (`npm test`, `cargo test`, `pytest`, etc.).
+3. Requires no interactive local debugging or visual UI tweaking.
+4. Does NOT modify restricted files (`.github/`, deployment keys, or unreviewed database migrations).
+
+---
+
+## 2. MCP Machine Directive & Read-Before-Write Invariants
+
+```xml
+<MCP_DIRECTIVE>
+  <system_state>HEADLESS_CI_MODE</system_state>
+  <strict_invariants>
+    <rule>1. NO CONVERSATION: Output ONLY machine-actionable tool calls or valid patches. No conversational filler or superlatives.</rule>
+    <rule>2. READ-BEFORE-WRITE (ZERO HALLUCINATION): You are FORBIDDEN from guessing internal API signatures. Before editing, you MUST use code search or MCP doc tools to inspect exact function signatures.</rule>
+    <rule>3. VERIFICATION LOOP: After patching code, you MUST execute the project's verification commands (tests/build) and ensure 0 errors.</rule>
+    <rule>4. ABORT CONDITION: On repeated unresolvable test failures (4+ attempts), output <status>ABORT_UNRESOLVABLE</status> and terminate immediately.</rule>
+  </strict_invariants>
+</MCP_DIRECTIVE>
+```
+
+---
+
+## 3. Dynamic Command Resolution
+
+Jules automatically infers test and build verification commands based on project manifest files:
+- `package.json` -> `npm run check:all && npm test && npm run build`
+- `Cargo.toml` -> `cargo test --workspace && cargo build`
+- `go.mod` -> `go test ./... && go build ./...`
+- `pyproject.toml` -> `pytest`
+- `pom.xml` -> `mvn test`
+- `build.gradle` -> `./gradlew test`
+- `.agent/jules.yml` -> Custom user commands
+
+---
+
+## 4. Operational & Code Quality Directives
+
+- **Read Before Write**: Always inspect target files and surrounding symbol signatures (via grep or view tools) before applying changes.
+- **Rebase Before PR**: Fetch latest `main`, rebase onto `origin/main`, re-execute verification suite. If the resulting diff is empty, close/abort PR without pushing.
+- **Minimal Interference**: Preserve existing function signatures, comments, and style conventions.
+- **Falsifiable Claims**: Base all code changes on explicit error logs, file paths, line numbers, or test results.
+- **No Token Bloat**: Exclude lockfiles, minified bundles, and binary assets from diff representations.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,128 @@
+# Google Jules Orchestration Kit
+
+A lightweight, framework-agnostic toolkit for turning **Google Jules** into a deterministic, autonomous background code builder for any repository (Next.js, Vite, Node, Bun, Deno, Python, Go, Rust, Elixir, Ruby, Swift, Java, C/C++, Monorepos, etc.).
+
+> **TL;DR**: Don't use Google Jules like a chat assistant. Use it as an autonomous background worker. Run `npx github:FullThrottle83/jules-orchestrator-kit` inside any repository to automatically detect your tech stack, generate prompt guardrails, set up test/build verification gates, and install Jules orchestration scripts.
+
+---
+
+## ⚡ 1-Step Quick Setup for Any Project
+
+Run this command inside the root of **any target repository**:
+
+```bash
+npx github:FullThrottle83/jules-orchestrator-kit
+```
+
+This single command will:
+1. **Detect your tech stack & workspace structure** (Node, Bun, Deno, Rust, Go, Python, Elixir, Ruby, Swift, Java, C/C++, Turborepo, Nx, pnpm) via `command-resolver.mjs`.
+2. **Generate `AGENTS.md`** pre-populated with pre-execution `<MCP_DIRECTIVE>` rules and verification invariants.
+3. **Create `.agent/jules.yml` (v2 Schema)** pre-configured with detected test/build commands and glob-based `forbidden_paths`.
+4. **Install `.agent/rules/dynamic-guardrails.json`** for RegEx-based dynamic prompt guardrail injection.
+5. **Install orchestration scripts** into `./scripts/` (`jules-dispatch.mjs`, `jules-self-audit.mjs`, `jules-swarm.mjs`, `jules-queue-runner.mjs`, `jules-nightly.mjs`).
+
+---
+
+## 💡 What This Toolkit Provides
+
+1. **Init Scaffolding CLI (`bin/init.js`)**: Auto-scaffolds any repo in 1 second.
+2. **Monorepo & Command Resolver (`scripts/command-resolver.mjs`)**: Auto-detects project manifests and monorepo workspace graphs (`turbo.json`, `pnpm-workspace.yaml`, `nx.json`, `Cargo.toml` workspaces) to run targeted affected package verifications instead of full-repo test suites.
+3. **Dynamic Guardrail Composition (`.agent/rules/dynamic-guardrails.json`)**: RegEx-based rule matching that injects targeted stack guardrails into prompts on-the-fly.
+4. **Pre-Flight Secret Redaction & REST/stdin Dispatcher (`scripts/jules-dispatch.mjs`)**: Auto-redacts API keys (`ghp_`, `AKIA`, `sk-`, `Bearer`, RSA keys), streams prompts over REST / stdin to bypass OS `ARG_MAX` shell limits, and handles HTTP 429 rate limits.
+
+5. **PR Self-Auditor & Glob Boundary Gatekeeper (`scripts/jules-self-audit.mjs`)**: Unshallows git history in CI runners (`git fetch --unshallow`), filters token bloat, enforces dynamic glob-based security boundaries (`forbidden_paths`), and runs scoped workspace test suites.
+6. **Queue Runner (`scripts/jules-queue-runner.mjs`)**: Iterates through `.agent/jules-queue/`, dispatches queued markdown tasks, and moves finished tasks to `.agent/jules-queue/completed/`.
+7. **Rate-Limited Swarm Orchestrator (`scripts/jules-swarm.mjs`)**: Manages multi-task batches with controlled concurrency (`JULES_SWARM_CONCURRENCY`, default 3), staggered dispatches (1.5s interval), and batch cooldowns to eliminate API rate-limit thrashing.
+8. **Nightly Maintenance Suite (`scripts/jules-nightly.mjs`)**: Schedules automated background audits (security leak scans, WCAG accessibility checks, dead code pruning, unused env var cleanup).
+
+---
+
+## 🛠️ Usage Examples
+
+### Dispatch a single task to Jules
+
+```bash
+node scripts/jules-dispatch.mjs "Refactor rate limiter" "Implement sliding window rate limiting using Redis. Must pass tests."
+```
+
+### Dispatch an entire queue of markdown task specifications
+
+```bash
+npm run jules:queue
+```
+
+### Run Rate-Limited Swarm Dispatch
+
+```bash
+JULES_SWARM_CONCURRENCY=5 node scripts/jules-swarm.mjs tasks.json
+```
+
+### Run Nightly Maintenance Suite
+
+```bash
+node scripts/jules-nightly.mjs --dry-run
+```
+
+### Audit Jules PRs before merging
+
+```bash
+node scripts/jules-self-audit.mjs
+```
+
+---
+
+## 🛠️ Supported Language Manifests & Workspace Graphs
+
+The command resolver automatically sniffs your codebase and invokes the right verification chain:
+
+| 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 check:all` or `npm test` |
+| **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)** | `pom.xml` | `mvn test && mvn compile` |
+| **Java (Gradle)** | `build.gradle` | `./gradlew test && ./gradlew assemble` |
+| **C / C++** | `Makefile` | `make test && make build` |
+| **Custom Config (v2)** | `.agent/jules.yml` | Configurable `test_cmd`, `build_cmd`, `forbidden_paths` & `allow_paths` |
+
+---
+
+## ⚙️ Configuration (`.agent/jules.yml`)
+
+```yaml
+# Google Jules Repository Configuration (Version 2)
+version: 2
+test_cmd: "npm test"
+build_cmd: "npm run build"
+forbidden_paths:
+  - ".github/**"
+  - "**/secrets/**"
+  - "**/*.pem"
+  - "**/lock-manager/**"
+  - "scripts/jules-*"
+  - ".agent/jules.yml"
+allow_paths: []
+```
+
+> 🛡️ **Security Trust Model**: `allow_paths` is read **strictly from the target base branch** (`origin/main`), never from untrusted PR branches. Any path specified in `allow_paths` on `main` overrides the immutable default forbidden paths for automated background workers.
+
+
+
+---
+
+## 📜 License & Disclaimer
+
+MIT License - feel free to use, modify, and share!
+
+*Disclaimer: This is an independent open-source orchestration tool and is not officially affiliated with or endorsed by Google.*
+
+

package/bin/init.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveProjectCommands } from "../scripts/command-resolver.mjs";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const kitRoot = path.resolve(__dirname, "..");
+const targetDir = process.cwd();
+
+const isForce = process.argv.includes("--force") || process.argv.includes("-f");
+
+console.log("\n🚀 Initializing Google Jules Orchestration Kit...\n");
+console.log(`📁 Target Directory: ${targetDir}`);
+if (isForce) console.log("⚠️ Force mode enabled (existing files will be overwritten).");
+
+// 1. Detect Stack & Manifests
+const detected = resolveProjectCommands(targetDir);
+console.log(`🔍 Detected Project Type: ${detected.source}`);
+if (detected.testCmd || detected.buildCmd) {
+  console.log(`   - Test Command:  ${detected.testCmd || "(none)"}`);
+  console.log(`   - Build Command: ${detected.buildCmd || "(none)"}`);
+}
+
+// 2. Scaffold AGENTS.md / .agent/jules-protocol.md
+const agentsFile = path.join(targetDir, "AGENTS.md");
+const julesRulesSource = path.join(kitRoot, "JULES_RULES_TEMPLATE.md");
+
+if (!fs.existsSync(agentsFile) || isForce) {
+  if (fs.existsSync(julesRulesSource)) {
+    fs.copyFileSync(julesRulesSource, agentsFile);
+    console.log("✅ Created: AGENTS.md");
+  }
+} else {
+  console.log("ℹ️ AGENTS.md already exists (skipped overwrite).");
+}
+
+// 3. Scaffold .agent/ structure
+const agentDir = path.join(targetDir, ".agent");
+const rulesDir = path.join(agentDir, "rules");
+const queueDir = path.join(agentDir, "jules-queue");
+const completedQueueDir = path.join(queueDir, "completed");
+const workflowsDir = path.join(agentDir, "workflows");
+
+[agentDir, rulesDir, queueDir, completedQueueDir, workflowsDir].forEach((d) => {
+  if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
+});
+
+// Scaffold .agent/jules.yml
+const yamlConfigPath = path.join(agentDir, "jules.yml");
+if (!fs.existsSync(yamlConfigPath) || isForce) {
+  const yamlContent = `# Google Jules Repository Configuration (Version 2)
+version: 2
+test_cmd: "${detected.testCmd || "npm test"}"
+build_cmd: "${detected.buildCmd || "npm run build"}"
+forbidden_paths: [".github/**", "**/secrets/**", "**/*.pem", "**/lock-manager/**"]
+`;
+  fs.writeFileSync(yamlConfigPath, yamlContent, "utf-8");
+  console.log("✅ Created: .agent/jules.yml");
+}
+
+// Scaffold .agent/rules/dynamic-guardrails.json
+const dgcSource = path.join(kitRoot, ".agent/rules/dynamic-guardrails.json");
+const dgcTarget = path.join(rulesDir, "dynamic-guardrails.json");
+if ((!fs.existsSync(dgcTarget) || isForce) && fs.existsSync(dgcSource)) {
+  fs.copyFileSync(dgcSource, dgcTarget);
+  console.log("✅ Created: .agent/rules/dynamic-guardrails.json");
+}
+
+// Scaffold .agent/workflows/jules-review.md
+const reviewSource = path.join(kitRoot, ".agent/workflows/jules-review.md");
+const reviewTarget = path.join(workflowsDir, "jules-review.md");
+if ((!fs.existsSync(reviewTarget) || isForce) && fs.existsSync(reviewSource)) {
+  fs.copyFileSync(reviewSource, reviewTarget);
+  console.log("✅ Created: .agent/workflows/jules-review.md");
+}
+
+// 4. Copy scripts/ directory with PER-FILE existence guard
+const targetScriptsDir = path.join(targetDir, "scripts");
+if (!fs.existsSync(targetScriptsDir)) {
+  fs.mkdirSync(targetScriptsDir, { recursive: true });
+}
+
+const sourceScriptsDir = path.join(kitRoot, "scripts");
+let copiedCount = 0;
+let skippedCount = 0;
+
+if (fs.existsSync(sourceScriptsDir)) {
+  const scriptFiles = fs.readdirSync(sourceScriptsDir);
+  scriptFiles.forEach((file) => {
+    const srcFile = path.join(sourceScriptsDir, file);
+    const destFile = path.join(targetScriptsDir, file);
+    if (!fs.existsSync(destFile) || isForce) {
+      fs.copyFileSync(srcFile, destFile);
+      try {
+        fs.chmodSync(destFile, 0o755);
+      } catch (_) {}
+      copiedCount++;
+    } else {
+      skippedCount++;
+    }
+  });
+  console.log(`✅ Copied ${copiedCount} orchestration scripts to ./scripts/ (${skippedCount} skipped, use --force to overwrite)`);
+}
+
+// 5. Optionally inject scripts into target package.json if present
+const targetPkgPath = path.join(targetDir, "package.json");
+if (fs.existsSync(targetPkgPath) && targetDir !== kitRoot) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(targetPkgPath, "utf-8"));
+    pkg.scripts = pkg.scripts || {};
+    let updated = false;
+    const julesScripts = {
+      "jules:dispatch": "node scripts/jules-dispatch.mjs",
+      "jules:queue": "node scripts/jules-queue-runner.mjs",
+      "jules:audit": "node scripts/jules-self-audit.mjs",
+      "jules:swarm": "node scripts/jules-swarm.mjs",
+      "jules:nightly": "node scripts/jules-nightly.mjs"
+    };
+
+    for (const [key, val] of Object.entries(julesScripts)) {
+      if (!pkg.scripts[key] || isForce) {
+        pkg.scripts[key] = val;
+        updated = true;
+      }
+    }
+
+    if (updated) {
+      fs.writeFileSync(targetPkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf-8");
+      console.log("✅ Injected jules:* helper scripts into package.json");
+    }
+  } catch (_) {}
+}
+
+console.log("\n🎉 Google Jules Orchestration Kit successfully initialized!");
+console.log("\nNext Steps:");
+console.log("  1. Set environment variables: JULES_REPO=\"owner/repo\"");
+console.log("  2. Dispatch your first task:  node scripts/jules-dispatch.mjs \"Task Title\" \"Task prompt\"");
+console.log("  3. Run pre-merge PR audit:    node scripts/jules-self-audit.mjs\n");
+

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "jules-orchestrator-kit",
+  "version": "0.1.0",
+  "description": "Framework-agnostic toolkit for orchestrating Google Jules background AI coding workers.",
+  "type": "module",
+  "bin": {
+    "jules-init": "bin/init.js",
+    "jules-orchestrator-kit": "bin/init.js"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "JULES_RULES_TEMPLATE.md",
+    "README.md",
+    "LICENSE"
+  ],
+
+  "scripts": {
+    "init": "node bin/init.js",
+    "test": "node --test test/kit.test.mjs",
+    "jules:dispatch": "node scripts/jules-dispatch.mjs",
+    "jules:queue": "node scripts/jules-queue-runner.mjs",
+    "jules:audit": "node scripts/jules-self-audit.mjs",
+    "jules:swarm": "node scripts/jules-swarm.mjs",
+    "jules:nightly": "node scripts/jules-nightly.mjs"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "jules",
+    "google-jules",
+    "ai-agent",
+    "orchestrator",
+    "mcp",
+    "automation"
+  ],
+  "author": "Jonas (FullThrottle83)",
+  "license": "MIT"
+}
+

package/scripts/command-resolver.mjs

@@ -0,0 +1,260 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Dynamic Framework-Agnostic Command Resolver
+ * Sniffs project manifests to return proper build & test verification commands.
+ */
+export function resolveProjectCommands(projectRoot = process.cwd()) {
+  // 1. Check for explicit custom config (.agent/jules.yml or jules.config.json)
+  const yamlConfigPath = path.join(projectRoot, ".agent/jules.yml");
+  if (fs.existsSync(yamlConfigPath)) {
+    const lines = fs.readFileSync(yamlConfigPath, "utf-8").split("\n");
+    let testCmd = "";
+    let buildCmd = "";
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) continue;
+      if (trimmed.startsWith("test_cmd:")) {
+        testCmd = trimmed.slice("test_cmd:".length).trim().replace(/^["']|["']$/g, "");
+      } else if (trimmed.startsWith("build_cmd:")) {
+        buildCmd = trimmed.slice("build_cmd:".length).trim().replace(/^["']|["']$/g, "");
+      }
+    }
+    if (testCmd || buildCmd) {
+      return {
+        testCmd,
+        buildCmd,
+        source: ".agent/jules.yml",
+      };
+    }
+  }
+
+  const jsonConfigPath = path.join(projectRoot, "jules.config.json");
+  if (fs.existsSync(jsonConfigPath)) {
+    try {
+      const cfg = JSON.parse(fs.readFileSync(jsonConfigPath, "utf-8"));
+      return {
+        testCmd: cfg.testCmd || cfg.verifyCmd || "",
+        buildCmd: cfg.buildCmd || "",
+        source: "jules.config.json",
+      };
+    } catch (_) {}
+  }
+
+  // 2. Bun (bunfig.toml or bun.lockb)
+  if (
+    fs.existsSync(path.join(projectRoot, "bunfig.toml")) ||
+    fs.existsSync(path.join(projectRoot, "bun.lockb"))
+  ) {
+    return {
+      testCmd: "bun test",
+      buildCmd: "bun run build",
+      source: "Bun Manifest",
+    };
+  }
+
+  // 3. Deno (deno.json / deno.jsonc)
+  if (
+    fs.existsSync(path.join(projectRoot, "deno.json")) ||
+    fs.existsSync(path.join(projectRoot, "deno.jsonc"))
+  ) {
+    return {
+      testCmd: "deno test",
+      buildCmd: "deno task build",
+      source: "Deno Manifest",
+    };
+  }
+
+  // 4. JavaScript / TypeScript (package.json)
+  const pkgPath = path.join(projectRoot, "package.json");
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+      const scripts = pkg.scripts || {};
+      const verifyScript = scripts["check:all"]
+        ? "npm run check:all"
+        : scripts.test
+        ? "npm test"
+        : "";
+      const buildScript = scripts.build ? "npm run build" : "";
+      return {
+        testCmd: verifyScript,
+        buildCmd: buildScript,
+        source: "package.json",
+      };
+    } catch (_) {}
+  }
+
+  // 5. Rust (Cargo.toml)
+  if (fs.existsSync(path.join(projectRoot, "Cargo.toml"))) {
+    return {
+      testCmd: "cargo test --workspace",
+      buildCmd: "cargo build",
+      source: "Cargo.toml",
+    };
+  }
+
+  // 6. Go (go.mod)
+  if (fs.existsSync(path.join(projectRoot, "go.mod"))) {
+    return {
+      testCmd: "go test ./...",
+      buildCmd: "go build ./...",
+      source: "go.mod",
+    };
+  }
+
+  // 7. Python (pyproject.toml / requirements.txt / setup.py)
+  if (
+    fs.existsSync(path.join(projectRoot, "pyproject.toml")) ||
+    fs.existsSync(path.join(projectRoot, "requirements.txt")) ||
+    fs.existsSync(path.join(projectRoot, "setup.py"))
+  ) {
+    return {
+      testCmd: "pytest",
+      buildCmd: "",
+      source: "Python Manifest",
+    };
+  }
+
+  // 8. Elixir (mix.exs)
+  if (fs.existsSync(path.join(projectRoot, "mix.exs"))) {
+    return {
+      testCmd: "mix test",
+      buildCmd: "mix compile",
+      source: "mix.exs",
+    };
+  }
+
+  // 9. Ruby (Gemfile)
+  if (fs.existsSync(path.join(projectRoot, "Gemfile"))) {
+    return {
+      testCmd: "bundle exec rake test",
+      buildCmd: "",
+      source: "Gemfile",
+    };
+  }
+
+  // 10. Swift (Package.swift)
+  if (fs.existsSync(path.join(projectRoot, "Package.swift"))) {
+    return {
+      testCmd: "swift test",
+      buildCmd: "swift build",
+      source: "Package.swift",
+    };
+  }
+
+  // 11. Java (Maven pom.xml / Gradle build.gradle)
+  if (fs.existsSync(path.join(projectRoot, "pom.xml"))) {
+    return {
+      testCmd: "mvn test",
+      buildCmd: "mvn compile",
+      source: "pom.xml",
+    };
+  }
+  if (
+    fs.existsSync(path.join(projectRoot, "build.gradle")) ||
+    fs.existsSync(path.join(projectRoot, "build.gradle.kts"))
+  ) {
+    return {
+      testCmd: "./gradlew test",
+      buildCmd: "./gradlew assemble",
+      source: "build.gradle",
+    };
+  }
+
+  // 12. Makefile
+  if (fs.existsSync(path.join(projectRoot, "Makefile"))) {
+    return {
+      testCmd: "make test",
+      buildCmd: "make build",
+      source: "Makefile",
+    };
+  }
+
+  return {
+    testCmd: "",
+    buildCmd: "",
+    source: "generic",
+  };
+}
+
+/**
+ * Resolves targeted build & test commands based on affected workspace packages.
+ * Prevents running O(N) full-repo test suites in monorepos when changes are localized.
+ */
+export function resolveWorkspaceExecutionBoundary(modifiedFiles = [], projectRoot = process.cwd()) {
+  const baseCmds = resolveProjectCommands(projectRoot);
+  if (!modifiedFiles || modifiedFiles.length === 0) return baseCmds;
+
+  // Find affected package names by walking up from modified files to nearest manifest
+  const affectedPkgs = new Set();
+  for (const file of modifiedFiles) {
+    let currentDir = path.resolve(projectRoot, path.dirname(file));
+    while (currentDir !== projectRoot && currentDir !== path.dirname(currentDir)) {
+      const pkgPath = path.join(currentDir, "package.json");
+      const cargoPath = path.join(currentDir, "Cargo.toml");
+      
+      if (fs.existsSync(pkgPath)) {
+        try {
+          const pkgData = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+          if (pkgData.name) affectedPkgs.add(pkgData.name);
+        } catch (_) {}
+        break;
+      } else if (fs.existsSync(cargoPath) && currentDir !== projectRoot) {
+        const cargoContent = fs.readFileSync(cargoPath, "utf-8");
+        const nameMatch = cargoContent.match(/name\s*=\s*["']([^"']+)["']/);
+        if (nameMatch) affectedPkgs.add(nameMatch[1]);
+        break;
+      }
+      currentDir = path.dirname(currentDir);
+    }
+  }
+
+  if (affectedPkgs.size === 0) return baseCmds;
+  const targets = Array.from(affectedPkgs);
+
+  // 1. Turborepo (turbo.json)
+  if (fs.existsSync(path.join(projectRoot, "turbo.json"))) {
+    const filters = targets.map((t) => `--filter=${t}...`).join(" ");
+    return {
+      buildCmd: `npx turbo run build ${filters}`,
+      testCmd: `npx turbo run test ${filters}`,
+      source: `Turborepo Workspace (${targets.join(", ")})`,
+    };
+  }
+
+  // 2. pnpm Workspace (pnpm-workspace.yaml)
+  if (fs.existsSync(path.join(projectRoot, "pnpm-workspace.yaml"))) {
+    const filters = targets.map((t) => `--filter=...${t}`).join(" ");
+    return {
+      buildCmd: `pnpm ${filters} build`,
+      testCmd: `pnpm ${filters} test`,
+      source: `pnpm Workspace (${targets.join(", ")})`,
+    };
+  }
+
+  // 3. Nx Workspace (nx.json)
+  if (fs.existsSync(path.join(projectRoot, "nx.json"))) {
+    const projects = targets.join(",");
+    return {
+      buildCmd: `npx nx run-many -t build -p ${projects} --with-deps`,
+      testCmd: `npx nx run-many -t test -p ${projects} --with-deps`,
+      source: `Nx Workspace (${targets.join(", ")})`,
+    };
+  }
+
+  // 4. Cargo Workspace (Cargo.toml in root with workspace)
+  const rootCargo = path.join(projectRoot, "Cargo.toml");
+  if (fs.existsSync(rootCargo) && fs.readFileSync(rootCargo, "utf-8").includes("[workspace]")) {
+    const filters = targets.map((t) => `-p ${t}`).join(" ");
+    return {
+      buildCmd: `cargo build ${filters}`,
+      testCmd: `cargo test ${filters}`,
+      source: `Cargo Workspace (${targets.join(", ")})`,
+    };
+  }
+
+  return baseCmds;
+}
+

package/scripts/jules-dispatch.mjs

@@ -0,0 +1,248 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import os from "node:os";
+import { resolveProjectCommands } from "./command-resolver.mjs";
+
+const taskTitle = process.argv[2];
+const taskPromptArg = process.argv[3];
+
+if (!taskTitle || !taskPromptArg) {
+  console.error(
+    'Usage: node scripts/jules-dispatch.mjs <task-title> <path-to-prompt.md | "raw prompt string">'
+  );
+  process.exit(1);
+}
+
+// 0. Environment Variables Auto-Load (.env support without extra dependencies)
+function loadEnv() {
+  const envPath = path.resolve(process.cwd(), ".env");
+  if (fs.existsSync(envPath)) {
+    const lines = fs.readFileSync(envPath, "utf-8").split("\n");
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) continue;
+      const eqIdx = trimmed.indexOf("=");
+      if (eqIdx > 0) {
+        const key = trimmed.slice(0, eqIdx).trim();
+        let val = trimmed.slice(eqIdx + 1).trim();
+        if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+          val = val.slice(1, -1);
+        }
+        if (!process.env[key]) {
+          process.env[key] = val;
+        }
+      }
+    }
+  }
+}
+loadEnv();
+
+// 0.1 Pre-Flight Secret Redaction Gate
+function redactSecrets(text) {
+  if (!text) return "";
+  const patterns = [
+    /gh[pusr]_[a-zA-Z0-9]{36}/g,
+    /github_pat_[a-zA-Z0-9]{22}_[a-zA-Z0-9]{59}/g,
+    /AKIA[0-9A-Z]{16}/g,
+    /AIzaSy[a-zA-Z0-9_\-]{33}/g,
+    /ya29\.[a-zA-Z0-9_\-]{20,}/g,
+    /Bearer\s+[a-zA-Z0-9\-\._~+\/]+=*/g,
+    /sk-(?:ant-api03-|proj-|svcacct-)[a-zA-Z0-9\-\_]{32,}/g,
+    /xox[baprs]-[a-zA-Z0-9\-]{10,}/g,
+    /eyJ[a-zA-Z0-9_\-]{10,}\.[a-zA-Z0-9_\-]{10,}\.[a-zA-Z0-9_\-]{10,}/g,
+    /-----BEGIN (?:RSA|OPENSSH|EC|PRIVATE) KEY-----[\s\S]*?-----END (?:RSA|OPENSSH|EC|PRIVATE) KEY-----/,
+  ];
+  let sanitized = text;
+  for (const pat of patterns) {
+    sanitized = sanitized.replace(pat, "[REDACTED_BY_SECURITY_GATE]");
+  }
+  return sanitized;
+}
+
+// 1. Resolve prompt content (file path or inline string)
+let rawPrompt = "";
+const possiblePath = path.resolve(process.cwd(), taskPromptArg);
+if (fs.existsSync(possiblePath) && fs.statSync(possiblePath).isFile()) {
+  rawPrompt = fs.readFileSync(possiblePath, "utf-8");
+} else {
+  rawPrompt = taskPromptArg;
+}
+rawPrompt = redactSecrets(rawPrompt);
+
+// 2. Dynamic Guardrail Composition (DGC) from .agent/rules/dynamic-guardrails.json
+function getDynamicGuardrails(promptText) {
+  const guardrailsPath = path.resolve(process.cwd(), ".agent/rules/dynamic-guardrails.json");
+  if (!fs.existsSync(guardrailsPath)) return "";
+
+  try {
+    const data = JSON.parse(fs.readFileSync(guardrailsPath, "utf-8"));
+    if (!data.rules || !Array.isArray(data.rules)) return "";
+
+    const active = [];
+    for (const item of data.rules) {
+      if (new RegExp(item.trigger, "i").test(promptText)) {
+        active.push(item.guardrail);
+      }
+    }
+    return active.join("\n\n");
+  } catch (e) {
+    return "";
+  }
+}
+
+// 3. Dynamic Command Resolution (Language & Framework Detection)
+const resolvedCmds = resolveProjectCommands(process.cwd());
+const verifyDirective = resolvedCmds.testCmd || resolvedCmds.buildCmd
+  ? `\n\n## 🛠️ MANDATORY VERIFICATION COMMANDS\nBefore submitting PR, you MUST execute: \`${[resolvedCmds.testCmd, resolvedCmds.buildCmd].filter(Boolean).join(" && ")}\``
+  : "";
+
+// 4. Load Base Rules / Guardrails
+const rulesPath = fs.existsSync(path.resolve(process.cwd(), "AGENTS.md"))
+  ? path.resolve(process.cwd(), "AGENTS.md")
+  : path.resolve(process.cwd(), "JULES_RULES_TEMPLATE.md");
+
+const baseRules = fs.existsSync(rulesPath)
+  ? fs.readFileSync(rulesPath, "utf-8")
+  : "";
+
+const dynamicRules = getDynamicGuardrails(rawPrompt);
+
+// Machine XML Directives
+const envelope = `
+<MCP_DIRECTIVE>
+  <system_state>HEADLESS_CI_MODE</system_state>
+  <strict_invariants>
+    <rule>1. READ-BEFORE-WRITE (ZERO HALLUCINATION): You are FORBIDDEN from guessing internal API signatures. Before editing, use search tools or MCP doc tools to verify exact signatures.</rule>
+    <rule>2. VERIFICATION LOOP: After patching code, you MUST execute the verification commands and ensure 0 errors.</rule>
+    <rule>3. ABORT CONDITION: On repeated unresolvable test failures, output <status>ABORT_UNRESOLVABLE</status> and terminate.</rule>
+  </strict_invariants>
+</MCP_DIRECTIVE>
+`.trim();
+
+const fullPrompt = redactSecrets(`MCP DIRECTIVE: ${rawPrompt.trim()}${verifyDirective}\n\n---\n\n${envelope}\n\n---\n\n${dynamicRules ? `${dynamicRules}\n\n---\n\n` : ""}${baseRules.trim()}`);
+
+// 5. Log Dispatch History
+const dateStr = new Date().toISOString().split("T")[0];
+const slug = taskTitle.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
+
+const historyDir = path.resolve(process.cwd(), ".agent/history");
+if (!fs.existsSync(historyDir)) {
+  fs.mkdirSync(historyDir, { recursive: true });
+}
+const historyFile = path.join(historyDir, `${dateStr}-dispatch-${slug}.md`);
+fs.writeFileSync(historyFile, `---\ntype: jules_dispatch\ntitle: "${taskTitle}"\ntimestamp: "${new Date().toISOString()}"\n---\n# Jules Task Dispatch: ${taskTitle}\n\n## Prompt\n${rawPrompt}\n`, "utf-8");
+
+console.log(`🚀 Dispatching task to Google Jules: "${taskTitle}"...`);
+console.log(`📝 Logged dispatch history to: ${path.relative(process.cwd(), historyFile)}`);
+
+// 6. Dispatch via REST API or Ephemeral Payload File (Avoid ARG_MAX shell limits)
+const apiKey = process.env.JULES_API_KEY;
+const repo = process.env.JULES_REPO;
+
+const payloadHash = crypto.createHash("sha256").update(taskTitle + Date.now()).digest("hex").slice(0, 12);
+const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "jules-payload-"));
+const tmpPayloadFile = path.join(tmpDir, `payload_${payloadHash}.json`);
+fs.writeFileSync(tmpPayloadFile, JSON.stringify({ repo, title: taskTitle, prompt: fullPrompt }), { mode: 0o600 });
+
+function cleanupTmp() {
+  try {
+    if (fs.existsSync(tmpDir)) {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  } catch (_) {}
+}
+
+async function executeDispatch() {
+  try {
+    if (apiKey && repo) {
+      console.log(`🌐 Using Jules REST API for repository ${repo}...`);
+      const formattedSource = repo.startsWith("sources/") ? repo : (repo.includes("/") ? `sources/github/${repo}` : repo);
+      const payload = {
+        title: taskTitle,
+        prompt: fullPrompt,
+        sourceContext: {
+          source: formattedSource,
+          githubRepoContext: {
+            startingBranch: process.env.BASE_BRANCH || "main"
+          }
+        }
+      };
+
+      let res;
+      try {
+        res = await fetch("https://jules.googleapis.com/v1alpha/sessions", {
+          method: "POST",
+          headers: {
+            "X-Goog-Api-Key": apiKey,
+            "Content-Type": "application/json"
+          },
+          body: JSON.stringify(payload)
+        });
+      } catch (fetchErr) {
+        console.warn(`⚠️ REST API request failed (network error), falling back to CLI...`, fetchErr.message);
+        dispatchViaCli(repo, tmpPayloadFile, taskTitle);
+        return;
+      }
+
+      if (res.status === 429) {
+        console.error(`❌ Jules REST API Rate Limit Exceeded (HTTP 429). Will NOT fallback to CLI.`);
+        process.exit(1);
+      }
+
+      if (!res.ok) {
+        const errText = await res.text().catch(() => "");
+        console.warn(`⚠️ REST API returned HTTP ${res.status}: ${errText}, falling back to CLI...`);
+        dispatchViaCli(repo, tmpPayloadFile, taskTitle);
+        return;
+      }
+
+      let sessionId = "Created";
+      try {
+        const data = await res.json();
+        sessionId = data.name || data.id || sessionId;
+      } catch (_) {}
+
+      console.log(`✅ REST API Dispatch response: Session ${sessionId} created successfully.`);
+      fs.appendFileSync(historyFile, `\n## Session\n- ID: \`${sessionId}\`\n`);
+    } else {
+      dispatchViaCli(repo, tmpPayloadFile, taskTitle);
+    }
+  } finally {
+    cleanupTmp();
+  }
+}
+
+
+function dispatchViaCli(targetRepo, payloadFile, title) {
+  try {
+    let promptToSend = fullPrompt;
+    if (payloadFile && fs.existsSync(payloadFile)) {
+      try {
+        const payloadData = JSON.parse(fs.readFileSync(payloadFile, "utf-8"));
+        if (payloadData.prompt) promptToSend = payloadData.prompt;
+      } catch (_) {}
+    }
+
+    const args = ["new"];
+    if (targetRepo) {
+      args.push("--repo", targetRepo);
+    }
+
+    console.log(`💻 Executing: jules ${args.join(" ")} (prompt passed via stdin)...`);
+    execFileSync("jules", args, { input: promptToSend, stdio: ["pipe", "inherit", "inherit"] });
+    console.log(`✅ Successfully dispatched task "${title}" to Jules CLI.`);
+  } catch (error) {
+    console.error(`❌ Failed to dispatch task to Jules CLI:`, error.message);
+    process.exit(1);
+  }
+}
+
+
+executeDispatch().catch((err) => {
+  console.error("❌ Fatal unhandled rejection in dispatch:", err);
+  process.exit(1);
+});
+
+

package/scripts/jules-nightly.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+/**
+ * Framework-Agnostic Nightly Jules Maintenance & Audit Suite Runner (Node ESM)
+ * Dispatches scheduled automated code health & maintenance tasks to Google Jules.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+
+const isDryRun = process.argv.includes("--dry-run");
+
+const UNIVERSAL_NIGHTLY_TASKS = [
+  {
+    id: "sec-review",
+    title: "Nightly Security & Secret Leaks Audit",
+    prompt:
+      "Perform a security review of the repository. " +
+      "Scan for hardcoded API keys, exposed secrets, unmasked PII in logs, " +
+      "and unvalidated input parameters in public endpoints. " +
+      "Safety rule: Never commit untracked files or secrets to git."
+  },
+  {
+    id: "a11y-audit",
+    title: "Nightly Accessibility & ARIA Audit",
+    prompt:
+      "Audit UI components for WCAG 2.2 AA accessibility standards. " +
+      "Verify that form inputs have labels, interactive elements support keyboard focus, " +
+      "and all images have descriptive alt text."
+  },
+  {
+    id: "dead-code-prune",
+    title: "Nightly Dead Code & Unused Exports Audit",
+    prompt:
+      "Audit the codebase for unused exports, dead files, and obsolete types. " +
+      "Prune unused local utility functions and unreferenced internal types. " +
+      "SAFETY INVARIANTS: " +
+      "1. DO NOT remove package dependencies from package.json, Cargo.toml, or requirements.txt (hygiene sweeps may ADD dependencies, never REMOVE). " +
+      "2. DO NOT delete or commit untracked WIP files created by developers. " +
+      "3. Verify that test and build suites pass 100% cleanly before submitting PR."
+  },
+  {
+    id: "zombie-env-audit",
+    title: "Nightly Unused Environment Variable Audit",
+    prompt:
+      "Scan configuration files and environment variable declarations against codebase usage. " +
+      "Identify unused or zombie environment variables that are declared but never referenced in source code. " +
+      "Document findings and remove obsolete declarations."
+  }
+];
+
+function logNightlyHistory(taskResults, dryRun = false) {
+  const dateStr = new Date().toISOString().split("T")[0];
+  const historyDir = path.resolve(process.cwd(), ".agent/history");
+  if (!fs.existsSync(historyDir)) {
+    fs.mkdirSync(historyDir, { recursive: true });
+  }
+  const historyFile = path.join(historyDir, `${dateStr}-nightly-audit.md`);
+
+  const modeLabel = dryRun ? "[DRY RUN]" : "[DISPATCHED]";
+  let content = `---\ntype: nightly_jules_audit\ntimestamp: "${new Date().toISOString()}"\nstatus: "${modeLabel}"\n---\n# Nightly Jules Maintenance Suite Audit - ${dateStr}\n\nSummary of automated audit dispatches:\n\n`;
+
+  for (const res of taskResults) {
+    content += `- **${res.title}** (\`${res.id}\`): ${res.status}\n`;
+  }
+
+  fs.writeFileSync(historyFile, content, "utf-8");
+  console.log(`📝 Logged nightly audit summary to: ${path.relative(process.cwd(), historyFile)}`);
+}
+
+function dispatchTask(task, dryRun = false) {
+  const title = task.title;
+  const fullPrompt = task.prompt;
+
+  console.log(`\n🌙 [${task.id}] Preparing task: '${title}'...`);
+
+  if (dryRun) {
+    console.log(`   [DRY RUN] Would dispatch task '${title}' to target repository`);
+    return { id: task.id, title, status: "Dry Run OK" };
+  }
+
+  const dispatchScript = path.resolve(process.cwd(), "scripts/jules-dispatch.mjs");
+  if (fs.existsSync(dispatchScript)) {
+    try {
+      execFileSync("node", [dispatchScript, title, fullPrompt], { stdio: "inherit" });
+      return { id: task.id, title, status: "Dispatched successfully" };
+    } catch (error) {
+      console.error(`❌ Failed to dispatch via jules-dispatch.mjs: ${error.message}`);
+      return { id: task.id, title, status: `Failed: ${error.message}` };
+    }
+  } else {
+    console.error(`❌ Dispatch script not found at ${dispatchScript}`);
+    return { id: task.id, title, status: "Failed (Script missing)" };
+  }
+}
+
+function main() {
+  console.log("==================================================");
+  console.log("🌙 Nightly Jules Maintenance & Audit Suite");
+  console.log("==================================================");
+
+  if (isDryRun) {
+    console.log("🔍 Running in DRY RUN mode. No tasks will be dispatched.");
+  }
+
+  const results = [];
+  for (const task of UNIVERSAL_NIGHTLY_TASKS) {
+    const res = dispatchTask(task, isDryRun);
+    results.push(res);
+  }
+
+  logNightlyHistory(results, isDryRun);
+  console.log("\n✅ Nightly Jules audit suite execution completed cleanly.");
+}
+
+main();

package/scripts/jules-queue-runner.mjs

@@ -0,0 +1,51 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+
+const queueDir = path.resolve(process.cwd(), ".agent/jules-queue");
+const completedDir = path.resolve(process.cwd(), ".agent/jules-queue/completed");
+
+if (!fs.existsSync(queueDir)) {
+  console.error(`❌ Queue directory not found: ${queueDir}`);
+  process.exit(1);
+}
+
+if (!fs.existsSync(completedDir)) {
+  fs.mkdirSync(completedDir, { recursive: true });
+}
+
+const files = fs.readdirSync(queueDir).filter(
+  (f) => f.endsWith(".md") && f !== "README.md" && !f.startsWith("_") && !f.startsWith(".")
+);
+
+
+if (files.length === 0) {
+  console.log("ℹ️ No tasks found in the queue.");
+  process.exit(0);
+}
+
+console.log(`🐝 Found ${files.length} tasks in the queue. Processing...`);
+
+files.forEach((file, index) => {
+  const filePath = path.join(queueDir, file);
+  // Generate title from filename (e.g. "TASK-001-auth-spec.md" -> "TASK 001 auth spec")
+  const title = file.replace(/\.md$/, "").replace(/-/g, " ");
+  
+  console.log(`\n----------------------------------------`);
+  console.log(`[${index + 1}/${files.length}] Dispatching queued task: ${title}`);
+  
+  try {
+    execFileSync("node", ["scripts/jules-dispatch.mjs", title, filePath], {
+      stdio: "inherit",
+    });
+    
+    // Move to completed
+    const destPath = path.join(completedDir, file);
+    fs.renameSync(filePath, destPath);
+    console.log(`✅ Moved ${file} to completed/`);
+  } catch (error) {
+    console.error(`⚠️ Failed to dispatch task [${title}]:`, error.message);
+  }
+});
+
+console.log(`\n🎉 Queue processing complete!`);

package/scripts/jules-self-audit.mjs

@@ -0,0 +1,196 @@
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveWorkspaceExecutionBoundary } from "./command-resolver.mjs";
+
+function runCommand(cmd, ignoreError = false) {
+  try {
+    return execSync(cmd, { encoding: "utf-8" }).trim();
+  } catch (error) {
+    if (ignoreError) return "";
+    console.error(`❌ Command failed: ${cmd}`);
+    console.error(error.message);
+    process.exit(1);
+  }
+}
+
+export function matchGlob(filepath, globPattern) {
+  const cleanPath = filepath.replace(/\\/g, "/").replace(/^\.\//, "");
+  const segments = globPattern.split("/");
+  const regexParts = [];
+  for (let i = 0; i < segments.length; i++) {
+    const seg = segments[i];
+    if (seg === "**") {
+      regexParts.push("**");
+    } else {
+      regexParts.push(
+        seg
+          .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+          .replace(/\*/g, "[^/]*")
+          .replace(/\?/g, ".")
+      );
+    }
+  }
+  let patternStr = regexParts.join("/");
+  patternStr = patternStr.replace(/(^|\/)\*\*(\/|$)/g, (m, p1, p2) => {
+    if (p1 === "/" && p2 === "/") return "(?:/|/.*/)";
+    if (p1 === "/") return "(?:/.*)?";
+    if (p2 === "/") return "(?:.*/)?";
+    return ".*";
+  });
+  return new RegExp(`^${patternStr}$`, "i").test(cleanPath);
+}
+
+
+export function loadForbiddenPatterns(configContent = "") {
+  const defaultForbidden = [
+    ".github/**",
+    "**/secrets/**",
+    "**/*.pem",
+    "**/lock-manager/**",
+    "scripts/jules-*",
+    ".agent/jules.yml"
+  ];
+  if (!configContent) return defaultForbidden;
+
+  // Flow style: forbidden_paths: [...]
+  const flowMatch = configContent.match(/forbidden_paths:\s*\[([^\]]+)\]/);
+  if (flowMatch) {
+    const parsed = flowMatch[1].split(",").map((s) => s.trim().replace(/^["']|["']$/g, "")).filter(Boolean);
+    return Array.from(new Set([...defaultForbidden, ...parsed]));
+  }
+
+  // Block style: forbidden_paths:\n  - "path1"\n  - "path2"
+  const lines = configContent.split("\n");
+  let inForbidden = false;
+  const blockParsed = [];
+  for (const line of lines) {
+    if (line.trim().startsWith("forbidden_paths:")) {
+      inForbidden = true;
+      continue;
+    }
+    if (inForbidden) {
+      const trimmed = line.trim();
+      if (trimmed.startsWith("-")) {
+        blockParsed.push(trimmed.slice(1).trim().replace(/^["']|["']$/g, ""));
+      } else if (trimmed && !trimmed.startsWith("#")) {
+        break;
+      }
+    }
+  }
+  if (blockParsed.length > 0) {
+    return Array.from(new Set([...defaultForbidden, ...blockParsed]));
+  }
+
+  return defaultForbidden;
+}
+
+export function loadAllowedPatterns(configContent = "") {
+  if (!configContent) return [];
+  const flowMatch = configContent.match(/allow_paths:\s*\[([^\]]+)\]/);
+  if (flowMatch) {
+    return flowMatch[1].split(",").map((s) => s.trim().replace(/^["']|["']$/g, "")).filter(Boolean);
+  }
+  const lines = configContent.split("\n");
+  let inAllow = false;
+  const blockParsed = [];
+  for (const line of lines) {
+    if (line.trim().startsWith("allow_paths:")) {
+      inAllow = true;
+      continue;
+    }
+    if (inAllow) {
+      const trimmed = line.trim();
+      if (trimmed.startsWith("-")) {
+        blockParsed.push(trimmed.slice(1).trim().replace(/^["']|["']$/g, ""));
+      } else if (trimmed && !trimmed.startsWith("#")) {
+        break;
+      }
+    }
+  }
+  return blockParsed;
+}
+
+export function runSelfAudit() {
+  console.log("🔍 Running Jules PR Self-Audit Gatekeeper...\n");
+
+  const targetBranch = process.env.BASE_BRANCH || "main";
+  console.log(`🎯 Target Branch: ${targetBranch}`);
+
+  if (process.env.CI) {
+    console.log("☁️ CI environment detected. Fetching merge-base history...");
+    runCommand(`git fetch origin ${targetBranch} --depth=100 || git fetch origin ${targetBranch} --unshallow`, true);
+  }
+
+  const mainRef = runCommand(`git rev-parse --verify origin/${targetBranch}`, true) ? `origin/${targetBranch}` : targetBranch;
+  const mergeBase = runCommand(`git merge-base HEAD ${mainRef}`, true);
+
+  if (!mergeBase) {
+    console.error(`❌ FATAL: Could not compute merge-base with ${mainRef}. Make sure git history is unshallowed.`);
+    process.exit(1);
+  }
+
+  console.log(`🔗 Merge-Base Hash: ${mergeBase}`);
+
+  const rawDiffFiles = runCommand(`git diff --name-only ${mergeBase}...HEAD`)
+    .split("\n")
+    .map((f) => f.trim())
+    .filter(Boolean);
+
+  const isBloatFile = (file) => /(\.lock|package-lock\.json|yarn\.lock|pnpm-lock\.yaml|\.png|\.jpg|\.jpeg|\.pdf|\.min\.js|\.map)$/i.test(file);
+  const changedCodeFiles = rawDiffFiles.filter((f) => !isBloatFile(f));
+
+  console.log(`\n📄 Modified Code Files (${changedCodeFiles.length} of ${rawDiffFiles.length} total changes):`);
+  changedCodeFiles.forEach((file) => console.log(`   - ${file}`));
+
+  // Fail closed: Load security config exclusively from base branch (mainRef).
+  // Never fall back to working-tree config which an untrusted PR could craft.
+  const trustedConfig = runCommand(`git show ${mainRef}:.agent/jules.yml`, true);
+  const forbiddenPatterns = loadForbiddenPatterns(trustedConfig);
+  const allowedPatterns = loadAllowedPatterns(trustedConfig);
+
+
+  const violations = rawDiffFiles.filter((file) => {
+    const isForbidden = forbiddenPatterns.some((pattern) => matchGlob(file, pattern));
+    if (!isForbidden) return false;
+    const isAllowed = allowedPatterns.some((pattern) => matchGlob(file, pattern));
+    return !isAllowed;
+  });
+
+  if (violations.length > 0) {
+    console.error("\n❌ RESTRICTED FILE VIOLATION DETECTED!");
+    console.error("Jules PR attempted to modify forbidden system files:");
+    violations.forEach((v) => console.error(`   - ${v}`));
+    process.exit(1);
+  }
+  console.log("\n✅ Restricted File Boundary Check: PASSED");
+
+
+  console.log("\n🛠️ Resolving Dynamic Verification Suite...");
+  const resolvedCmds = resolveWorkspaceExecutionBoundary(changedCodeFiles, process.cwd());
+  console.log(`📋 Discovered Execution Scope: ${resolvedCmds.source}`);
+
+  if (resolvedCmds.testCmd) {
+    console.log(`▶ Running Test Verification: ${resolvedCmds.testCmd}`);
+    runCommand(resolvedCmds.testCmd);
+  }
+  if (resolvedCmds.buildCmd) {
+    console.log(`▶ Running Build Verification: ${resolvedCmds.buildCmd}`);
+    runCommand(resolvedCmds.buildCmd);
+  }
+
+  if (!resolvedCmds.testCmd && !resolvedCmds.buildCmd) {
+    console.log("ℹ️ No build or test scripts found. Running git status check.");
+    runCommand("git status");
+  }
+
+  console.log("\n🎉 JULES PR SELF-AUDIT PASSED SUCCESSFULLY!");
+}
+
+// Execute when invoked directly from CLI
+if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url))) {
+  runSelfAudit();
+}
+
+

package/scripts/jules-swarm.mjs

@@ -0,0 +1,87 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import fs from "node:fs";
+import path from "node:path";
+
+const execFileAsync = promisify(execFile);
+
+const tasksFile = process.argv[2];
+
+if (!tasksFile) {
+  console.error("Usage: node scripts/jules-swarm.mjs <path-to-tasks.json>");
+  console.error('Format of tasks.json: [ { "id": "t1", "title": "Task 1", "prompt": "Description 1" } ]');
+  process.exit(1);
+}
+
+const resolvedPath = path.resolve(process.cwd(), tasksFile);
+if (!fs.existsSync(resolvedPath)) {
+  console.error(`❌ Tasks file not found: ${resolvedPath}`);
+  process.exit(1);
+}
+
+const tasks = JSON.parse(fs.readFileSync(resolvedPath, "utf-8"));
+if (!Array.isArray(tasks)) {
+  console.error("❌ tasks.json must contain a JSON array of task objects.");
+  process.exit(1);
+}
+
+const MAX_CONCURRENT = parseInt(process.env.JULES_SWARM_CONCURRENCY || "3", 10);
+const STAGGER_MS = parseInt(process.env.JULES_SWARM_STAGGER_MS || "1500", 10);
+
+console.log(`🐝 Launching Jules Swarm Orchestrator (${tasks.length} tasks, Concurrency: ${MAX_CONCURRENT})...`);
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+async function runSwarm() {
+  const results = [];
+
+  for (let i = 0; i < tasks.length; i += MAX_CONCURRENT) {
+    const batch = tasks.slice(i, i + MAX_CONCURRENT);
+    const batchResults = await Promise.allSettled(
+      batch.map(async (task, bIdx) => {
+        const taskNum = i + bIdx + 1;
+        const taskId = task.id || `task-${taskNum}`;
+
+        if (bIdx > 0) {
+          await sleep(STAGGER_MS * bIdx);
+        }
+
+        console.log(`\n----------------------------------------`);
+        console.log(`[${taskNum}/${tasks.length}] Dispatching Swarm Task: ${task.title} (${taskId})`);
+
+        try {
+          const { stdout } = await execFileAsync("node", ["scripts/jules-dispatch.mjs", task.title, task.prompt], {
+            timeout: 15 * 60 * 1000,
+          });
+          if (stdout) console.log(stdout.trim());
+          return { taskId, title: task.title, status: "SUCCESS" };
+        } catch (error) {
+          console.error(`⚠️ Failed task [${task.title}]:`, error.message);
+          return { taskId, title: task.title, status: "FAILED", error: error.message };
+        }
+      })
+    );
+
+    for (const r of batchResults) {
+      if (r.status === "fulfilled") {
+        results.push(r.value);
+      } else {
+        results.push({ title: "Unknown Task", status: "FAILED", error: r.reason });
+      }
+    }
+
+    if (i + MAX_CONCURRENT < tasks.length) {
+      console.log(`\n⏳ Batch finished. Cooling down for 2s before next batch...`);
+      await sleep(2000);
+    }
+  }
+
+  console.log(`\n========================================`);
+  console.log(`🎉 Swarm Dispatch Summary (${results.length} tasks processed):`);
+  results.forEach((res) => {
+    console.log(`  - [${res.status}] ${res.title}`);
+  });
+}
+
+runSwarm();
+