jules-orchestrator-kit 0.3.0 → 0.5.2

package/README.md

@@ -1,126 +1,171 @@
 # Google Jules Orchestration Kit 🤖⚡
 
+[![Status](https://img.shields.io/badge/Status-Alpha-orange.svg)](#)
 [![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)](#)
 
-A lightweight, zero-dependency toolkit that upgrades **Google Jules** into a **fully autonomous, self-correcting background code builder** for any repository (Next.js, Vite, Node, Bun, Deno, Python, Go, Rust, Elixir, Ruby, Swift, Java, C/C++, Monorepos, etc.).
+**Turn Google Jules into an autonomous code builder that writes, tests, and fixes itself.**
 
-Whether you are a beginner looking to automate bug fixes without breaking your app, or a power user orchestrating parallel AI task swarms, this kit handles the heavy lifting of prompting, testing, security, and verification.
+> [!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**: Don't just chat with Google Jules—put it to work. Run `npx jules-orchestrator-kit` inside your project. Assign tasks, and the kit will automatically test the AI's code, tell it to fix any mistakes, and only present you with working, tested Pull Requests.
+> **💡 TL;DR**: Run `npx jules-orchestrator-kit` in your repo, assign tasks, and get working, tested Pull Requests—no manual review needed.
 
 ---
 
-## 🎯 Who is this for?
+## 🎯 Is This For You?
 
-**🌱 For Everyday Developers:**  
-AI agents can write broken code or skip tests. This kit acts as an automated safety net: it detects your tech stack, runs your tests against the AI's code, catches errors, and prompts the AI to self-correct *before* you review the Pull Request.
-
-**🔥 For Power Users & Senior Engineers:**  
-Unlock deterministic, production-grade orchestration. Includes Git Worktree multi-task swarms, Shannon Entropy secret redaction, MCP (Model Context Protocol) directive envelopes, OODA self-healing feedback loops, and scope boundary locks.
+| **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 |
 
 ---
 
-## 🚀 Quick Start: Zero to Autonomous AI
-
-### 1. Initialize your project
-Run this command inside the root of **any target repository**. It automatically detects your tech stack and sets up safety guardrails:
+## 🚀 Get Started in 2 Minutes
 
+### 1. Initialize (Auto-detects your tech stack)
+Navigate to your project root and run:
 ```bash
 npx jules-orchestrator-kit
+```
 
-# Or launch the interactive setup wizard:
-npx jules-init --interactive
+### 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"
 ```
 
-### 2. Dispatch your first task
-Once initialized, you can immediately send tasks to Jules. The Orchestrator handles prompting, testing, security, and self-correction in the background:
+### 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
-node scripts/jules-dispatch.mjs "Refactor rate limiter" "Implement sliding window rate limiting in src/utils/rate-limit.ts"
+npm run jules:status
 ```
 
-*(**Pro-tip:** Add `JULES_DRY_RUN=1` before the command to test prompt generation locally without executing the remote API).*
+**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.5.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: The Autonomous Loop
+## 🤖 How It Works
+
+### Simple Version (For Everyone)
 
-Instead of blindly trusting AI code mutations, the Orchestrator acts as a strict manager enforcing a **Tiered Verification Gate**:
+```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. **Queue a Task:** Dispatch via CLI, REST API, or drop markdown files into `.agent/jules-queue/`.
-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-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.
+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
+```
+
+> 💡 **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 System Architecture Diagram (For Power Users)</b></summary>
+<summary><b>🔍 View Detailed Sequence Diagram (Step-by-Step Execution Protocol)</b></summary>
 
 ```mermaid
 sequenceDiagram
     autonumber
-    participant CLI as CI Trigger / CLI
-    participant Orc as jules-orchestrator
-    participant Jules as Google Jules Agent
-    participant Git as Git Worktree Sandbox
+    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
 
-    CLI->>Orc: Dispatch Task ("Refactor Auth")
+    Trigger->>Orc: Dispatch Task Payload
     
-    note over Orc,Git: Phase 1: Isolation & Setup
-    Orc->>Orc: Redact Secrets & Check Path Traversal
-    Orc->>Git: Provision Worktree (`git worktree add`)
-    Orc->>Jules: Dispatch Context, Invariants & Target Scope
+    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
 
-    Jules->>Git: Propose Code Mutations
+    API->>Git: Apply Proposed Code Changes
     
-    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`)
+    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 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)
+    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>
 
 ---
 
-## 💡 Core Capabilities (8 Component Suite)
-
-### 🛠️ The Basics
-
-* **Auto-Configuration (`bin/init.js`)**: Instantly scaffolds your repo using `node:util.parseArgs` with an interactive TTY wizard (`-i`) or silent CI fallback.
-* **Queue Runner (`scripts/jules-queue-runner.mjs`)**: Drop markdown task specifications into `.agent/jules-queue/` and let the runner process them sequentially.
-* **Nightly Maintenance (`scripts/jules-nightly.mjs`)**: Schedules automated background audits (security leak scans, WCAG accessibility checks, dead code pruning).
-
-### 🔒 Security & Guardrails
-
-* **Secret & Traversal Redaction (`scripts/jules-dispatch.mjs`)**: Shannon Entropy detector strips API keys and secrets (`entropy > 3.6`, `length >= 20`) while preserving valid file paths. Supports dry-run testing (`JULES_DRY_RUN=1`).
-* **Dynamic Guardrails (`.agent/rules/dynamic-guardrails.json`)**: RegEx-based rule matching that injects targeted stack guardrails into prompts on-the-fly.
-
-### 🐝 Advanced Orchestration
-
-* **Monorepo Boundary Resolver (`scripts/command-resolver.mjs`)**: Auto-detects `turbo`, `nx`, `pnpm`, or `Cargo` workspaces to run targeted affected package verifications (`git diff`) instead of full-repo test suites.
-* **Self-Healing Gatekeeper (`scripts/jules-self-audit.mjs`)**: Unshallows git history in CI runners (`git fetch --unshallow`), enforces `forbidden_paths`, extracts OODA feedback error traces, and logs telemetry to `.agent/history/metrics.jsonl`.
-* **Git Worktree Swarms (`scripts/jules-swarm.mjs`)**: Manages multi-task batches in isolated Git worktrees (`JULES_USE_WORKTREES=true`) with scope boundary isolation.
-
----
+## ⚙️ Configuration
 
-## ⚙️ Configuration & Zero-Trust Security
+### Custom Configuration (`.agent/jules.yml`)
 
-The orchestrator creates an `.agent/jules.yml` file to manage repo-level verification and security:
+The orchestrator automatically detects your tech stack, but you can edit `.agent/jules.yml` for fine-grained control:
 
 ```yaml
 # Google Jules Repository Configuration (Version 2)
@@ -137,118 +182,128 @@ forbidden_paths:
 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.
+> 🛡️ **Zero-Trust Security Model**: Configuration is always read from your target base branch (`origin/main`), never from untrusted PR branches.
 
 ---
 
-<details>
-<summary><b>🛠️ Supported Language Manifests & Workspace Graphs (15+ Tech Stacks)</b></summary>
-
-| 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>
+## 💡 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 3 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`                                   |
 
 ---
 
-<details>
-<summary><b>📖 Advanced Workflows (Queues, Swarms, Nightly Maintenance)</b></summary>
+## 🔌 Expand with MCP (Model Context Protocol)
 
-### 1. Process an entire queue of background tasks
+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**.
 
-```bash
-npm run jules:queue
-```
+**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:
 
-### 2. Run Rate-Limited Swarms with Scope Isolation
+* **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.
 
-Run massive parallel refactors safely. The orchestrator uses `tasks.json` file boundary `scope` segregation to prevent parallel task collisions:
+By feeding these MCPs into your ecosystem, Jules can automatically read the latest framework documentation or query your live database schema before writing code!
 
-```bash
-JULES_SWARM_CONCURRENCY=5 JULES_USE_WORKTREES=true node scripts/jules-swarm.mjs tasks.json
-```
+---
 
-*(Example `tasks.json` constraint: `[ { "id": "t1", "prompt": "Refactor auth", "scope": ["src/auth/**"] } ]`)*
+## 🌐 Integration Interfaces
 
-### 3. Run Nightly Maintenance Suite
+The orchestrator supports two primary integration channels for manual tasks:
 
-```bash
-node scripts/jules-nightly.mjs --dry-run
-```
+**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.
 
-### 4. Audit Jules PRs before merging in CI
+**2. Native Jules CLI Fallback**
+If no API key is configured, the kit seamlessly falls back to invoking your local `jules` CLI binary via standard streams.
 
-```bash
-node scripts/jules-self-audit.mjs
+**3. Programmatic Node.js SDK (`index.mjs`)**
+Downstream Node.js tools, MCP servers, and LLM orchestrators can import kit functions directly:
+```js
+import { runSelfAudit, scanCodebaseForTodos, resolveProjectCommands } from "jules-orchestrator-kit";
+
+// Run pre-flight sandbox check
+await runPreflightSandbox();
+
+// Scan codebase for TODO/FIXME tasks
+const tasks = scanCodebaseForTodos(process.cwd());
 ```
 
-</details>
+---
+
+## ⚠️ Known Limitations & Workarounds
+
+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)
+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.
 
 ---
 
+## 📦 Supported Tech Stacks
+
 <details>
-<summary><b>🌐 Integration Interfaces: CLI, REST API & MCP Directives</b></summary>
-
-`jules-orchestrator-kit` 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 (`.env` or CI secrets), payloads are dispatched directly to the official Google Jules REST API endpoint.
-- Handles HTTP 429 rate limits gracefully.
-- Automatically maps `startingBranch` and `sourceContext`.
-
-### 2. Native Jules CLI Fallback (`jules new`)
-If no API key is configured, the kit seamlessly falls back to invoking your local `jules` CLI binary. Prompts are piped directly via `stdin` to bypass OS `ARG_MAX` shell argument length limits.
-
-### 3. MCP (Model Context Protocol) Directives
-All task dispatches dynamically inject `<MCP_DIRECTIVE>` envelopes into task prompts:
-```xml
-<MCP_DIRECTIVE>
-  <system_state>HEADLESS_CI_MODE</system_state>
-  <strict_invariants>
-    <rule>1. READ-BEFORE-WRITE: Inspect symbol definitions before editing.</rule>
-    <rule>2. VERIFICATION LOOP: Execute test_cmd and pass with 0 errors.</rule>
-    <rule>3. ABORT CONDITION: Terminate on 4+ repeated test failures.</rule>
-    <rule>4. ASSERTION QUALITY: Unit tests created or modified MUST contain explicit assertions.</rule>
-  </strict_invariants>
-</MCP_DIRECTIVE>
-```
-This forces Jules to adhere to strict read-before-write invariants and deterministic execution when operating alongside MCP server tools.
+<summary><b>🛠️ View Supported Language Manifests & Workspace Graphs</b></summary>
+
+| Stack / Ecosystem           | Manifest / Workspace File             | Test Command                             | Build Command                            |
+| --------------------------- | ------------------------------------- | ---------------------------------------- | ---------------------------------------- |
+| **Turborepo**               | `turbo.json`                          | `npx turbo run test --filter=...`        | `npx turbo run build --filter=...`       |
+| **pnpm Workspace**          | `pnpm-workspace.yaml`                 | `pnpm --filter=... test`                 | `pnpm --filter=... build`                |
+| **Nx Workspace**            | `nx.json`                             | `npx nx run-many -t test -p ...`         | `npx nx run-many -t build -p ...`        |
+| **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 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>
 
 ---
 
-<details>
-<summary><b>🤝 Contributing & Code Guidelines</b></summary>
-
-We welcome contributions! Please follow these core principles when submitting Pull Requests:
+## 🤝 Contributing
 
-1. **Zero External Dependencies**: Keep the orchestrator engine 100% dependency-free. 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 commit message prefixes (`feat:`, `fix:`, `docs:`, `test:`, `chore:`).
-4. **Cross-Platform Compatibility**: Always normalize Windows backslashes (`\`) to POSIX slashes (`/`) for glob patterns and paths.
+We welcome contributions! Please follow these core principles:
 
-</details>
+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
 
 ---
 
-## 📜 License & Disclaimer
+## 📜 License
 
 MIT License - feel free to use, modify, and share!
 

package/bin/init.js

@@ -5,6 +5,8 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
 import readline from "node:readline/promises";
+import zlib from "node:zlib";
+import crypto from "node:crypto";
 import { resolveProjectCommands } from "../scripts/command-resolver.mjs";
 
 const __filename = fileURLToPath(import.meta.url);
@@ -57,10 +59,13 @@ if (isForce) console.log("⚠️ Force mode enabled (existing files will be over
 let answerRepoVal = "";
 let answerBranchVal = "";
 
-// Dual TTY Interactive Wizard
 if (process.stdin.isTTY && (isInteractive || (!fs.existsSync(path.join(targetDir, ".agent/jules.yml")) && !process.env.CI))) {
   try {
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.on('SIGINT', () => {
+      console.log("\n🛑 Initialization aborted by user.");
+      process.exit(130);
+    });
     const answerRepo = await rl.question("📦 Enter target GitHub repository (e.g. owner/repo) [optional]: ");
     if (answerRepo.trim()) {
       answerRepoVal = answerRepo.trim();
@@ -73,6 +78,10 @@ if (process.stdin.isTTY && (isInteractive || (!fs.existsSync(path.join(targetDir
     }
     rl.close();
   } catch (err) {
+    if (err.name === 'AbortError') {
+      console.log("\n🛑 Initialization aborted by user.");
+      process.exit(130);
+    }
     console.warn("⚠️ Interactive setup prompt failed:", err.message);
   }
 }
@@ -181,7 +190,7 @@ if (fs.existsSync(auditWfSource)) {
   }
   if (!fs.existsSync(auditWfTarget) || isForce) {
     fs.copyFileSync(auditWfSource, auditWfTarget);
-    console.log("✅ Scaffolded CI Audit Workflow: .github/workflows/jules-audit.yml");
+    console.log("✅ Added GitHub Actions workflow: .github/workflows/jules-audit.yml");
   }
 }
 
@@ -225,6 +234,8 @@ if (fs.existsSync(targetPkgPath) && targetDir !== kitRoot) {
     const julesScripts = {
       "jules:dispatch": "node scripts/jules-dispatch.mjs",
       "jules:queue": "node scripts/jules-queue-runner.mjs",
+      "jules:create": "node scripts/jules-create.mjs",
+      "jules:status": "node scripts/jules-status.mjs",
       "jules:audit": "node scripts/jules-self-audit.mjs",
       "jules:swarm": "node scripts/jules-swarm.mjs",
       "jules:nightly": "node scripts/jules-nightly.mjs"
@@ -239,7 +250,7 @@ if (fs.existsSync(targetPkgPath) && targetDir !== kitRoot) {
 
     if (updated) {
       fs.writeFileSync(targetPkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf-8");
-      console.log("✅ Injected jules:* helper scripts into package.json");
+      console.log("✅ Added Jules commands to package.json");
     }
   } catch (err) {
     console.warn("⚠️ Failed to inject helper scripts into target package.json:", err.message);
@@ -247,7 +258,55 @@ if (fs.existsSync(targetPkgPath) && targetDir !== kitRoot) {
 }
 
 console.log("\n🎉 Google Jules Orchestration Kit successfully initialized!");
+
+// 6. Generate Cryptographic Handshake (JULES_WEB_SETUP.md)
+const agentState = {
+  v: 1,
+  schema: "jules.init/v1",
+  generatedAt: new Date().toISOString(),
+  repo: {
+    name: answerRepoVal || process.env.JULES_REPO || "unknown/repo",
+    branch: answerBranchVal || process.env.BASE_BRANCH || "main"
+  },
+  workspace: {
+    testCmd: detected.testCmd || "",
+    buildCmd: detected.buildCmd || "",
+    source: detected.source || "unknown"
+  }
+};
+
+const canonicalJson = JSON.stringify(agentState);
+const hash = crypto.createHash("sha256").update(canonicalJson, "utf8").digest("hex");
+const compressed = zlib.brotliCompressSync(Buffer.from(canonicalJson, "utf8"));
+const payloadToken = `JULES1.${hash}.${compressed.toString("base64url")}`;
+
+const setupMdContent = `# JULES Web Setup
+
+> **Generated**: ${agentState.generatedAt}
+> **Setup Code**: \`${payloadToken}\`
+
+## 🔗 Web Dashboard Setup
+1. Open Jules Web UI (https://app.jules.ai/setup)
+2. Paste your Setup Code:
+\`\`\`
+${payloadToken}
+\`\`\`
+
+## 🔧 Detected Configuration
+* Test Command: \`${agentState.workspace.testCmd}\`
+* Build Command: \`${agentState.workspace.buildCmd}\`
+* Source: \`${agentState.workspace.source}\`
+`;
+
+fs.writeFileSync(path.join(targetDir, ".agent", "JULES_WEB_SETUP.md"), setupMdContent, "utf-8");
+
+console.log("\n🔗 Web Dashboard Setup");
+console.log("  Your local agent configurations are ready.");
+console.log(`  👉 Setup Code: \x1b[36m${payloadToken}\x1b[0m`);
+console.log("\n  (A backup of this setup code was written to .agent/JULES_WEB_SETUP.md)");
 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");
+console.log("  1. Paste the Setup Code into Jules Web UI.");
+console.log("  2. Set environment variables: JULES_REPO=\"owner/repo\"");
+console.log("  3. Scaffold a new task: npm run jules:create \"My Feature\"");
+console.log("  4. Dispatch the queue:  npm run jules:queue");
+console.log("  5. Run pre-merge audit: npm run jules:audit\n");

package/index.mjs

@@ -0,0 +1,11 @@
+/**
+ * jules-orchestrator-kit Node.js SDK
+ * Primary entrypoint for programmatically orchestrating Google Jules workflows.
+ * Zero external dependencies.
+ */
+
+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";