jules-orchestrator-kit 0.5.1 → 0.6.0

package/.agent/jules.yml

@@ -7,7 +7,7 @@ forbidden_paths:
   - "**/secrets/**"
   - "**/*.pem"
   - "**/lock-manager/**"
-  - "scripts/jules-*"
+  - "scripts/jules-self-audit.mjs"
   - ".agent/jules.yml"
 allow_paths: []
 

package/.env.example

@@ -1,17 +1,63 @@
 # Google Jules Orchestration Kit - Environment Configuration Example
 # Copy this file to .env and populate with your credentials/settings.
 
+# --- Authentication & Core Settings ---
 # Google Jules API Key (Required for direct REST API dispatches)
 JULES_API_KEY=your_google_jules_api_key_here
 
+# Alias for API key (fallback if JULES_API_KEY is not set)
+# GEMINI_API_KEY=your_gemini_api_key_here
+
+# Override the Jules REST API URL
+# JULES_API_URL=https://jules.googleapis.com/v1alpha/sessions
+
 # Target GitHub Repository (Format: owner/repo)
-JULES_REPO=FullThrottle83/jules-orchestrator-kit
+JULES_REPO=owner/repo
+
+# Set to "true" or "1" to run in repoless/serverless mode
+# JULES_REPOLESS=false
+
+# Enable Dry-Run mode to simulate payload dispatch without making API calls
+# JULES_DRY_RUN=false
 
+# --- Execution Scope & Git ---
 # Base Branch for PR Audits & Merge-Base Calculations (Default: main)
 BASE_BRANCH=main
 
-# Swarm Concurrency Limit (Maximum parallel dispatches, default: 3)
+# PR Head Branch (Used by CI to dynamically target branches during OODA repair)
+# GITHUB_HEAD_REF=my-feature-branch
+
+# Root directory of the project (Auto-assigned during swarm executions)
+# JULES_PROJECT_ROOT=/path/to/project
+
+# --- Swarm & Concurrency ---
+# Maximum parallel dispatches for swarm runs (Default: 3)
 JULES_SWARM_CONCURRENCY=3
 
-# Swarm Dispatch Stagger Interval in Milliseconds (Default: 1500)
+# Dispatch Stagger Interval in Milliseconds (Default: 1500)
 JULES_SWARM_STAGGER_MS=1500
+
+# Rate-limit for the jules:queue command (Default: 500)
+# JULES_PACE_MS=500
+
+# Use Git Worktrees instead of cloning for swarm isolation
+# JULES_USE_WORKTREES=false
+
+# Current slot index for partitioning tasks (Swarm mode)
+# JULES_SLOT_INDEX=1
+
+# Total number of slots for partitioning tasks (Swarm mode)
+# JULES_SLOT_TOTAL=3
+
+# --- CI & Output ---
+# Is this running in a CI environment? (Changes log output and fail-fast behaviors)
+# CI=true
+
+# Allow OODA Auto-Repair even in CI environments
+# ALLOW_AUTO_REPAIR=true
+
+# GitHub Actions Step Summary File Path
+# GITHUB_STEP_SUMMARY=/path/to/step_summary.md
+
+# Disable color in terminal output
+# NO_COLOR=true

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,63 @@
+name: Bug Report
+description: Create a report to help us improve Jules Orchestrator Kit
+title: "[BUG] "
+labels: ["bug"]
+assignees: []
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out this bug report!
+  - type: input
+    id: version
+    attributes:
+      label: "Node.js Version"
+      description: "What version of Node.js are you using? (e.g. v20.11.0)"
+      placeholder: "v20.x"
+    validations:
+      required: true
+  - type: dropdown
+    id: package_manager
+    attributes:
+      label: "Package Manager"
+      description: "Which package manager are you using?"
+      options:
+        - npm
+        - pnpm
+        - yarn
+        - bun
+    validations:
+      required: true
+  - type: dropdown
+    id: execution_mode
+    attributes:
+      label: "Execution Mode"
+      description: "How are you running Jules?"
+      options:
+        - API Mode (JULES_API_KEY set)
+        - CLI Mode (Local jules binary)
+    validations:
+      required: true
+  - type: textarea
+    id: description
+    attributes:
+      label: "Bug Description"
+      description: "A clear and concise description of what the bug is."
+      placeholder: "When I run npm run jules:queue..."
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: "Steps to Reproduce"
+      description: "Steps to reproduce the behavior."
+      placeholder: "1. Go to...\n2. Click on...\n3. See error"
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: "Expected Behavior"
+      description: "A clear and concise description of what you expected to happen."
+    validations:
+      required: true

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,34 @@
+name: Feature Request
+description: Suggest an idea for Jules Orchestrator Kit
+title: "[FEATURE] "
+labels: ["enhancement"]
+assignees: []
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting a new feature!
+  - type: textarea
+    id: description
+    attributes:
+      label: "Is your feature request related to a problem? Please describe."
+      description: "A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]"
+      placeholder: "..."
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: "Describe the solution you'd like"
+      description: "A clear and concise description of what you want to happen."
+      placeholder: "..."
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: "Describe alternatives you've considered"
+      description: "A clear and concise description of any alternative solutions or features you've considered."
+      placeholder: "..."
+    validations:
+      required: false

package/.github/workflows/agent-scope-guard.yml

@@ -23,12 +23,13 @@ jobs:
         env:
           BASE_SHA: ${{ github.event.pull_request.base.sha }}
           HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          BASE_REF: ${{ github.base_ref }}
         run: |
           echo "Checking files modified in PR..."
           MODIFIED_FILES=$(git diff --name-only $BASE_SHA $HEAD_SHA)
           
-          # Read protected paths
-          PROTECTED_PATHS=$(node -e "const paths = require('./.agent/protected-paths.json').protected; console.log(paths.join(' '));")
+          # Read protected paths from origin/${{ github.base_ref }}
+          PROTECTED_PATHS=$(node -e "const paths = JSON.parse(require('child_process').execSync('git show origin/' + process.env.BASE_REF + ':.agent/protected-paths.json', {encoding:'utf8'})).protected; console.log(paths.join(' '));")
           
           echo "Protected patterns: $PROTECTED_PATHS"
           

package/.github/workflows/jules-audit.yml

@@ -9,6 +9,9 @@ on:
 jobs:
   audit-and-test:
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: ['18.x', '20.x', '22.x', '24.x']
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -18,13 +21,16 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: "20"
+          node-version: ${{ matrix.node-version }}
+
+      - name: Syntax Check
+        run: for f in scripts/*.mjs bin/*.js index.mjs; do node --check "$f" || exit 1; done
 
       - name: Run Unit Tests
         run: npm test
 
       - name: Run Jules PR Self-Audit Gatekeeper
-        if: github.event_name == 'pull_request' && (startsWith(github.actor, 'google-labs-jules') || contains(github.actor, 'jules'))
+        if: matrix.node-version == '20.x' && github.event_name == 'pull_request' && (startsWith(github.actor, 'google-labs-jules') || contains(github.actor, 'jules'))
         run: node scripts/jules-self-audit.mjs
         env:
           CI: "true"

package/README.md

@@ -1,169 +1,53 @@
-# Google Jules Orchestration Kit 🤖⚡
+# jules-orchestrator-kit
 
-[![Status](https://img.shields.io/badge/Status-Alpha-orange.svg)](#)
+*Disclaimer: This is an independent open-source orchestration tool and is not officially affiliated with or endorsed by Google.*
+
+[![Jules PR Audit](https://github.com/FullThrottle83/jules-orchestrator-kit/actions/workflows/jules-audit.yml/badge.svg)](https://github.com/FullThrottle83/jules-orchestrator-kit/actions/workflows/jules-audit.yml)
 [![npm version](https://img.shields.io/npm/v/jules-orchestrator-kit.svg)](https://www.npmjs.com/package/jules-orchestrator-kit)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.0.0-green.svg)](https://nodejs.org)
-[![Zero Dependencies](https://img.shields.io/badge/Dependencies-0-blue.svg)](#)
 
 **Turn Google Jules into an autonomous code builder that writes, tests, and fixes itself.**
+The orchestrator automates verification, scopes file boundaries, and prevents Jules from breaking your CI.
 
 > [!WARNING]
 > **Alpha Release:** This kit is in active development. Please exercise caution before integrating it into critical production pipelines.
-> 
-> **Task Limit Warning:** Autonomous loops (like OODA self-healing or large swarms) can quickly consume your daily Google Jules task limits (e.g., 100 tasks/day on Pro, 300 tasks/day on Ultra). We strongly recommend starting with `JULES_DRY_RUN=1` to understand the workflow before scaling up!
-
-> **💡 TL;DR**: Run `npx jules-orchestrator-kit` in your repo, assign tasks, and get working, tested Pull Requests—no manual review needed.
 
----
-
-## 🎯 Is This For You?
+> [!CAUTION]
+> **Task Limit Warning:** Autonomous loops can quickly consume your daily API limits. We strongly recommend starting with `JULES_DRY_RUN=1` to understand the workflow before scaling up.
 
-| **Your Role**              | **What This Solves**                               | **Your Benefit**                                                          |
-| -------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------- |
-| **Busy Developer**         | AI writes broken code or skips tests               | Automatic safety net catches errors before you review                     |
-| **Team Lead**              | Need consistent quality from AI changes            | Enforces tests, linting, and scope boundaries automatically               |
-| **DevOps Engineer**        | Want to scale AI across many repos                 | Parallel task swarms with security guardrails                             |
-| **Open Source Maintainer** | Limited time to review AI contributions            | Self-correcting PRs that pass your CI                                     |
-| **Power User**             | Need deterministic, production-grade orchestration | Git Worktrees, entropy-based secret redaction, MCP directives, OODA loops |
+## Prerequisites
+To use this kit, you will need:
+- Node.js `18.0.0` or higher
+- `git` installed and available in your PATH
+- A Google Jules REST API key (set as `JULES_API_KEY`) **OR** the native `jules` binary in your PATH.
 
----
-
-## 🚀 Get Started in 2 Minutes
-
-### 1. Initialize (Auto-detects your tech stack)
+## Quick Start
 Navigate to your project root and run:
 ```bash
 npx jules-orchestrator-kit
-```
-
-### 2. Scaffold a Task
-Generate a clean boilerplate markdown file so you don't have to start from scratch:
-```bash
 npm run jules:create "Refactor Auth"
-```
-
-### 3. Queue and Track
-Edit the generated markdown file in `.agent/jules-queue/` and dispatch it:
-```bash
 npm run jules:queue
 ```
 
-You can view the real-time status of your dispatched tasks using:
-```bash
-npm run jules:status
-```
-
-**What just happened?**
-- Jules wrote code to fulfill your task.
-- The orchestrator ran your tests automatically.
-- If tests failed, Jules fixed the code and re-ran tests.
-- You'll receive a Pull Request with working, verified code.
-
-> 🔐 **New in v0.3.0 (The Epistemic Bridge)**: The init script generates a cryptographic Handshake Token (`.agent/JULES_WEB_SETUP.md`). Paste this into the Jules Web UI to sync your environment perfectly.
-
 ---
 
-## 🤖 How It Works
+## How It Works
 
-### Simple Version (For Everyone)
-
-```mermaid
-graph TD
-    A["You Assign Task"] --> B["Jules Writes Code<br/>in Sandbox"]
-    B --> C["Run Tests & Linters"]
-    C --> D{"Tests Pass?"}
-    D -->|Yes| E["Create PR for Review"]
-    D -->|No| F["Jules Fixes Code"]
-    F --> C
-```
-
-1. **You define the task** - "Fix the memory leak in the cache module"
-2. **Jules proposes changes** - In an isolated Git worktree sandbox
-3. **Automatic verification** - Runs your test suite, linters, and type checks
-4. **Self-correction** - If anything fails, Jules automatically retries with fixes
-5. **Safe delivery** - Only working, tested code reaches your main branch
-
-## 🏗️ Architecture & Pipeline Flow
-
-```mermaid
-graph TD
-    classDef start fill:#1f2937,stroke:#4b5563,color:#f9fafb;
-    classDef core fill:#111827,stroke:#374151,color:#f9fafb;
-    classDef gate fill:#1e1b4b,stroke:#4338ca,color:#e0e7ff;
-    classDef success fill:#064e3b,stroke:#059669,color:#ecfdf5;
-    classDef error fill:#4c0519,stroke:#e11d48,color:#fff1f2;
-
-    A["1. Client Trigger<br/><i>(CLI / CI / SDK / REST API)</i>"]:::start --> B["2. Orchestrator Core<br/><i>(Redaction & Guardrails)</i>"]:::core
-    B --> C["3. Google Jules Agent<br/><i>(Code Gen in Sandbox)</i>"]:::core
-    C --> D{"4. Gatekeeper<br/><i>(Scope & Tests)</i>"}:::gate
-    
-    D -->|Scope Breach| E["❌ Exit 3<br/>Security Violation"]:::error
-    D -->|100% Passed| F["✅ Exit 0<br/>Success & Log"]:::success
-    D -->|Test Failure| G{"5. OODA Repair<br/><i>(Retries < 3?)</i>"}:::gate
-    
-    G -->|Retry| C
-    G -->|Circuit Tripped| H["❌ Exit 4<br/>Diagnostic Abort"]:::error
-```
+1. **You Assign Task:** Define what needs fixing or building.
+2. **Jules Writes Code:** Proposes changes in an isolated Git worktree sandbox.
+3. **Run Tests & Linters:** The Gatekeeper runs your test suite, linters, and type checks.
+4. **Self-Correction:** If anything fails, Jules automatically retries with fixes (OODA loop).
+5. **Safe Delivery:** Once tests pass, the PR is verified and ready for review.
 
 > 💡 **Core Architectural Invariants**:
 > - **Zero-Trust Base-Branch Security**: Security rules (`forbidden_paths`) are fetched exclusively from `origin/main` (never untrusted PR branches).
 > - **Dynamic Command Resolution (`command-resolver.mjs`)**: Auto-detects workspace boundaries (Turborepo, pnpm, Nx, Cargo, pytest, npm).
-> - **SHA-256 OODA Circuit Breaker**: Fingerprints failure traces (`ooda-circuit.json`). Halts auto-repair if identical errors repeat.
-
-<details>
-<summary><b>🔍 View Detailed Sequence Diagram (Step-by-Step Execution Protocol)</b></summary>
-
-```mermaid
-sequenceDiagram
-    autonumber
-    actor Trigger as Client (CLI / CI / SDK)
-    participant Orc as Orchestrator Core
-    participant API as Google Jules API
-    participant Git as Git / Worktree Sandbox
-    participant Gate as Self-Audit Gatekeeper
-
-    Trigger->>Orc: Dispatch Task Payload
-    
-    note over Orc,Git: Phase 1: Security Redaction & Context Enrichment
-    Orc->>Orc: Redact Secrets (Entropy > 3.6) & Enforce Dynamic Guardrails
-    Orc->>Git: Provision Isolation Sandbox (Worktree / Repoless)
-    Orc->>API: Dispatch Task + <MCP_DIRECTIVE> & Target Scope
-
-    API->>Git: Apply Proposed Code Changes
-    
-    note over Orc,Gate: Phase 2: Tiered Verification & OODA Gatekeeper
-    Orc->>Gate: Trigger Self-Audit (fetch trusted origin/main rules)
-    Gate->>Git: Scope Audit (`git diff -z --name-only` vs forbidden_paths)
-    
-    alt Scope Breach (Forbidden Path Modified)
-        Gate-->>Orc: Security Violation Detected
-        Orc-->>Trigger: Abort Execution (Exit 3)
-    else Scope Verification Passed
-        Gate->>Git: Resolve & Run Dynamic Verification Suite (`test_cmd` & `build_cmd`)
-    end
-
-    alt 100% Verification Suite Passed
-        Gate->>Orc: Verification Success
-        Orc->>Git: Record Telemetry (`metrics.jsonl`)
-        Orc-->>Trigger: Dispatch Succeeded (Exit 0)
-    else Verification Failed (OODA Feedback Triggered)
-        Gate->>Gate: Fingerprint Trace (SHA-256 Error Hash & Check Circuit Breaker)
-        alt Auto-Repair Eligible (Retries < 3 & Circuit OK)
-            Gate->>API: Auto-Dispatch Repair Prompt with Stderr Trace
-        else Circuit Tripped / Max Retries Exceeded
-            Gate-->>Orc: Verification Exhausted
-            Orc-->>Trigger: Abort & Log Diagnostic Feedback (Exit 4)
-        end
-    end
-```
-</details>
+>
+> 🔍 For a deep dive into the execution protocol, see the [Architecture & Pipeline Flow](docs/architecture.md).
 
 ---
 
-## ⚙️ Configuration
-
-### Custom Configuration (`.agent/jules.yml`)
+## Configuration
 
 The orchestrator automatically detects your tech stack, but you can edit `.agent/jules.yml` for fine-grained control:
 
@@ -182,58 +66,22 @@ forbidden_paths:
 allow_paths: []
 ```
 
-> 🛡️ **Zero-Trust Security Model**: Configuration is always read from your target base branch (`origin/main`), never from untrusted PR branches.
-
 ---
 
-## 💡 Features
-
-### 🛡️ Core Safety (For Everyone)
-
-| Feature               | What It Does                                 | Example                               |
-| --------------------- | -------------------------------------------- | ------------------------------------- |
-| **Automatic Testing** | Runs test suite against every AI change      | `test_cmd: "npm test"`                |
-| **Self-Fixing**       | Jules automatically corrects failed tests    | Retries up to 4 times before blocking |
-| **Secret Protection** | Hides API keys, passwords, tokens            | Entropy > 3.6, length ≥ 20            |
-| **Path Restrictions** | Blocks changes to sensitive files            | `.env`, `*.pem`, `.github/**`         |
-| **Scope Boundaries**  | Prevents changes outside task scope          | `scope: ["src/auth/**"]`              |
-| **Agent Scope Guard** | CI-enforced protected paths manifestation    | `.agent/protected-paths.json`         |
-| **Payload Governor**  | Hard cap to prevent > 80 KB payload failures | Diffs capped at 75 KB                 |
-
-
-| Feature                 | Use Case                                  | Command                                    |
-| ----------------------- | ----------------------------------------- | ------------------------------------------ |
-| **Git Worktree Swarms** | Parallel tasks with slot isolation        | `node scripts/jules-swarm.mjs tasks.json`  |
-| **Suggested Scanner**   | Scan TODO/FIXME comments into task queues | `npm run jules:scan`                       |
-| **Session Cleanup**     | Audit & close merged/stale REST sessions  | `npm run jules:cleanup -- --close-merged`  |
-| **Repoless Sessions**   | Serverless ad-hoc analysis without repos  | `npm run jules:dispatch -- --repoless ...` |
-| **Monorepo Support**    | Auto-detects Turbo, Nx, pnpm, Cargo       | Runs affected package tests only           |
-| **Queue Pacing**        | Rate-limit queue launches (`--pace-ms`)   | `npm run jules:queue -- --pace-ms 500`     |
-| **Pre-Flight Sandbox**  | Test setup locally before cloud execution | `node scripts/jules-self-audit.mjs --preflight`                    |
-| **Security Fencing**    | Prompt injection defense & secret masking | Automatic `<UNTRUSTED_TASK_CONTEXT>` encapsulation                 |
-| **OODA Feedback**       | Self-healing from test failures           | Logs to `.agent/history/metrics.jsonl`                             |
-| **Mutex Lock Protocol** | Prevent concurrent file collisions        | `node scripts/lock-manager.mjs acquire`                            |
-| **Baton Pass Protocol** | Stateful handovers to human/other AI      | `.agent/history/*-handover-*.md`                                   |
-
----
-
-## 🔌 Expand with MCP (Model Context Protocol)
-
-All task dispatches dynamically inject `<MCP_DIRECTIVE>` envelopes into task prompts. This forces Jules to adhere to strict read-before-write invariants and deterministic execution when operating alongside **MCP server tools**.
-
-**Pro-tip:** You can supercharge Jules with external MCP servers! By connecting standard MCP servers to your environment, you give Jules direct access to your infrastructure and real-time documentation. Some powerful examples include:
+## Expand with MCP
 
-* **SaaS APIs & Tooling:** Context 7, Linear, and v0 for issue tracking and UI generation.
-* **Databases & Cloud:** Render, Neon, Supabase, Stitch, and Tinybird.
-* **Framework Documentation:** Astro Docs, Cloudflare Docs, Next.js Docs, etc.
+All task dispatches dynamically inject `<MCP_DIRECTIVE>` envelopes into task prompts. This forces Jules to adhere to strict read-before-write invariants.
 
-By feeding these MCPs into your ecosystem, Jules can automatically read the latest framework documentation or query your live database schema before writing code!
+You can supercharge Jules with external MCP servers by connecting them to your environment, granting Jules direct access to your infrastructure and real-time documentation. Examples:
+* **SaaS APIs & Tooling:** Context 7, Linear, and v0.
+* **Databases & Cloud:** Render, Neon, Supabase, Stitch.
+* **Framework Documentation:** Astro Docs, Cloudflare Docs, Next.js Docs.
 
 ---
 
-## 🌐 Integration Interfaces
+## Integration Interfaces
 
-The orchestrator supports two primary integration channels for manual tasks:
+The orchestrator supports three primary integration channels:
 
 **1. Direct REST API Mode (`jules.googleapis.com`)**
 When `JULES_API_KEY` and `JULES_REPO` are present in your environment, payloads are dispatched directly to the official Google Jules REST API endpoint. Handles HTTP 429 rate limits gracefully.
@@ -255,21 +103,16 @@ const tasks = scanCodebaseForTodos(process.cwd());
 
 ---
 
-## ⚠️ Known Limitations & Workarounds
+## Known Limitations
 
-While this kit automates the heavy lifting of code generation and PR creation, there are a few limitations in how it interacts with the underlying Jules platform:
-
-### Code Suggestions (Web UI Only)
+**Code Suggestions (Web UI Only)**
 Currently, there is no way to automatically extract "Suggestions" (the inline code review comments Jules sometimes proposes instead of direct commits) via the CLI or API. Suggestions can only be read directly inside the **Jules Web UI**.
 
-* **Workaround for Local LLM Users:** If you are tinkering with Jules alongside a local LLM (e.g., Claude, Cursor, Antigravity) and Jules leaves a Suggestion, the easiest workflow is to open the Jules Web UI, copy the suggestion block, and paste it back into your local LLM to let it review and integrate the proposed changes.
+*Workaround for Local LLM Users:* If you are tinkering with Jules alongside a local LLM and Jules leaves a Suggestion, the easiest workflow is to open the Jules Web UI, copy the suggestion block, and paste it back into your local LLM.
 
 ---
 
-## 📦 Supported Tech Stacks
-
-<details>
-<summary><b>🛠️ View Supported Language Manifests & Workspace Graphs</b></summary>
+## Supported Tech Stacks
 
 | Stack / Ecosystem           | Manifest / Workspace File             | Test Command                             | Build Command                            |
 | --------------------------- | ------------------------------------- | ---------------------------------------- | ---------------------------------------- |
@@ -288,23 +131,75 @@ Currently, there is no way to automatically extract "Suggestions" (the inline co
 | **Java (Maven/Gradle)**     | `pom.xml` / `build.gradle`            | `mvn test` / `./gradlew test`            | `mvn compile` / `./gradlew assemble`     |
 | **C / C++**                 | `Makefile`                            | `make test`                              | `make build`                             |
 
-</details>
-
 ---
 
-## 🤝 Contributing
-
-We welcome contributions! Please follow these core principles:
-
-1. **Zero External Dependencies**: Use ONLY native Node.js built-in modules (`node:fs`, `node:path`, `node:child_process`, `node:crypto`, `node:util`)
-2. **Verification Suite**: Ensure 100% of unit tests pass cleanly (`npm test`)
-3. **Conventional Commits**: Use standardized prefixes (`feat:`, `fix:`, `docs:`, `test:`, `chore:`)
-4. **Cross-Platform Compatibility**: Normalize Windows backslashes (`\`) to POSIX slashes (`/`) for glob patterns and paths
+## Reference Material
+
+### CLI Commands
+All commands are registered in `package.json` and can be run via `npm run <command>`.
+
+| Command | Description |
+| ------- | ----------- |
+| `npm run init` | Initializes the orchestrator and `.agent/` directory |
+| `npm run test` | Runs the orchestrator kit's own unit tests |
+| `npm run jules:dispatch` | Dispatches a single task directly to Jules |
+| `npm run jules:queue` | Runs the local queue processor (picks up tasks from `.agent/jules-queue`) |
+| `npm run jules:create` | Scaffolds a new boilerplate task markdown file |
+| `npm run jules:status` | Shows the real-time status of all queued and completed tasks |
+| `npm run jules:audit` | Runs the self-audit gatekeeper (verifies tests, forbidden paths, and scope) |
+| `npm run jules:cleanup` | Audits and closes merged or stale REST sessions |
+| `npm run jules:scan` | Scans the codebase for TODO/FIXME comments and generates a suggested tasks file |
+| `npm run jules:swarm` | Launches a multi-agent swarm in parallel across isolated worktrees |
+| `npm run jules:nightly` | Nightly maintenance job (usually triggered in CI) |
+
+### Environment Variables
+
+| Variable | Description |
+| -------- | ----------- |
+| `JULES_API_KEY` | Your Google Jules REST API key (required for API mode) |
+| `GEMINI_API_KEY` | Alias for `JULES_API_KEY` (fallback) |
+| `JULES_API_URL` | Override the Jules REST API URL |
+| `JULES_REPO` | Target GitHub Repository (Format: `owner/repo`) |
+| `JULES_REPOLESS` | Set to `true` or `1` to run in repoless/serverless mode |
+| `JULES_DRY_RUN` | Set to `true` or `1` to simulate dispatching without making API calls |
+| `BASE_BRANCH` | Base branch for PR Audits & Merge-Base calculations (Default: `main`) |
+| `GITHUB_HEAD_REF` | PR Head Branch (Used dynamically by CI during OODA repair) |
+| `JULES_PROJECT_ROOT` | Root directory of the project (Auto-assigned during swarm executions) |
+| `JULES_SWARM_CONCURRENCY` | Maximum parallel dispatches for swarm runs (Default: `3`) |
+| `JULES_SWARM_STAGGER_MS` | Dispatch stagger interval in milliseconds (Default: `1500`) |
+| `JULES_PACE_MS` | Rate-limit for the `jules:queue` command (Default: `500`) |
+| `JULES_USE_WORKTREES` | Use Git Worktrees instead of cloning for swarm isolation (Default: `false`) |
+| `JULES_SLOT_INDEX` | Current slot index for partitioning tasks (Swarm mode) |
+| `JULES_SLOT_TOTAL` | Total number of slots for partitioning tasks (Swarm mode) |
+| `CI` | Set to `true` to change log output and fail-fast behaviors for CI environments |
+| `ALLOW_AUTO_REPAIR` | Set to `true` to allow OODA Auto-Repair even when running in CI |
+| `GITHUB_STEP_SUMMARY` | GitHub Actions Step Summary File Path |
+| `NO_COLOR` | Set to `true` to disable ANSI color output |
+
+### Exit Codes
+The Gatekeeper (`jules-self-audit.mjs` and related scripts) uses standard exit codes to signal status to CI systems.
+
+| Code | Meaning | Action Taken |
+| ---- | ------- | ------------ |
+| `0`  | **Success** | All tests and security checks passed. |
+| `1`  | **General Error** | Missing dependencies, syntax error, or general failure. |
+| `2`  | **Setup / Context Error** | Git not found, invalid `BASE_BRANCH`, or trusted base branch extraction failure. |
+| `3`  | **Security Violation** | Modified file breached `forbidden_paths` or changed command-defining files (`package.json`, `Cargo.toml`). Fails closed immediately. |
+| `4`  | **Verification Exhausted** | Tests failed and the OODA Auto-Repair loop either exhausted its max retries or is disabled. |
+| `5`  | **Diff Payload Too Large** | Diff payload size exceeded 75 KB payload governor limit. Split task. |
+| `6`  | **Secret Leak Prevented** | Secret-like pattern detected in diff. Aborted immediately. |
+| `7`  | **Budget Exhausted** | Daily session budget limit reached or budget state locked. |
 
 ---
 
-## 📜 License
+## Contributing
+We welcome contributions! Please follow these core principles:
+1. **Zero External Dependencies**: Use ONLY native Node.js built-in modules (`node:fs`, `node:path`, `node:child_process`, `node:crypto`, `node:util`).
+2. **Verification Suite**: Ensure 100% of unit tests pass cleanly (`npm test`).
+3. **Conventional Commits**: Use standardized prefixes (`feat:`, `fix:`, `docs:`, `test:`, `chore:`).
+4. **Cross-Platform Compatibility**: Normalize Windows backslashes (`\`) to POSIX slashes (`/`) for glob patterns and paths.
 
-MIT License - feel free to use, modify, and share!
+Please read our [Code of Conduct](CODE_OF_CONDUCT.md) before participating.
 
-*Disclaimer: This is an independent open-source orchestration tool and is not officially affiliated with or endorsed by Google.*
+## License
+MIT License - feel free to use, modify, and share!

package/index.mjs

@@ -7,5 +7,5 @@
 export { resolveProjectCommands, resolveWorkspaceExecutionBoundary } from "./scripts/command-resolver.mjs";
 export { runSelfAudit, runPreflightSandbox, loadForbiddenPatterns, loadAllowedPatterns, matchGlob } from "./scripts/jules-self-audit.mjs";
 export { scanCodebaseForTodos, runScanner } from "./scripts/jules-scan-todos.mjs";
-export { log, logToHistory, ensureDir, resolveMarkdownConflict } from "./scripts/utils.mjs";
-export { redactSecrets, getDynamicGuardrails } from "./scripts/jules-dispatch.mjs";
+export { log, logToHistory, ensureDir, resolveMarkdownConflict, redactSecrets } from "./scripts/utils.mjs";
+export { getDynamicGuardrails } from "./scripts/jules-dispatch.mjs";

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "jules-orchestrator-kit",
-  "version": "0.5.1",
+  "version": "0.6.0",
+  "description": "Orchestration kit for running Google Jules autonomous agents.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/FullThrottle83/jules-orchestrator-kit.git"
@@ -56,6 +57,6 @@
     "mcp",
     "automation"
   ],
-  "author": "Google Open Source",
+  "author": "FullThrottle83",
   "license": "MIT"
 }

package/scripts/command-resolver.mjs

@@ -185,8 +185,8 @@ export function resolveWorkspaceExecutionBoundary(modifiedFiles = [], projectRoo
   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`,
+      buildCmd: `pnpm ${filters} run build`,
+      testCmd: `pnpm ${filters} run test`,
       source: `pnpm Workspace (${targets.join(", ")})`,
     };
   }