jules-orchestrator-kit 0.26.2 → 0.27.1

package/README.md

@@ -4,76 +4,115 @@
 
 ### Universal Autonomous AI Agent Orchestration Kernel for Google Jules
 
+<br/>
+
 [![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 Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org)
 [![Zero Dependencies](https://img.shields.io/badge/dependencies-0%20native-blue.svg)](https://nodejs.org)
-[![Polyglot Stacks](https://img.shields.io/badge/polyglot--stacks-24%2B-8A2BE2.svg)](#-universal-polyglot-support--stack-detection)
+
+<br/>
 
 <p align="center">
-  <b>The zero-dependency safety gatekeeper and self-healing engineering kernel for autonomous coding agent swarms.</b><br/>
+  <b>The zero-dependency safety gatekeeper and self-healing engineering kernel for autonomous coding agent swarms.</b>
   Transforms single-turn AI chat assistants into production-grade engineering swarms running 300+ daily sessions across any language or monorepo.
 </p>
 
+<br/>
+
 <p align="center">
-  <a href="#-2-sentence-mental-model">💡 What is Kit?</a> •
-  <a href="#-universal-30-second-quickstart-zero-to-verified-pr">⚡ 30s Quickstart</a> •
-  <a href="#-triage-guidelines-when-to-use-vs-when-not-to-use">🎯 Triage Guidelines</a> •
-  <a href="#-feature-comparison-matrix">📊 Comparison Matrix</a> •
-  <a href="#-system-architecture--visual-diagrams">🏛️ Architecture</a> •
-  <a href="#-cli-command-reference-agentctl">🛠️ CLI Reference</a> •
-  <a href="#-v027-next-gen-feature-roadmap">🗺️ Roadmap</a>
+  <a href="#what-is-kit">💡&nbsp;What&nbsp;is&nbsp;Kit?</a> &nbsp;•&nbsp;
+  <a href="#quickstart">⚡&nbsp;Quickstart</a> &nbsp;•&nbsp;
+  <a href="#triage-guidelines">🎯&nbsp;Triage&nbsp;Guidelines</a> &nbsp;•&nbsp;
+  <a href="#matrix">📊&nbsp;Matrix</a>
+  <br/>
+  <a href="#architecture">🏛️&nbsp;Architecture</a> &nbsp;•&nbsp;
+  <a href="#cli-docs">🛠️&nbsp;CLI&nbsp;Docs</a> &nbsp;•&nbsp;
+  <a href="#roadmap">🗺️&nbsp;Roadmap</a>
 </p>
 
 </div>
 
+<br/>
+
 ---
 
+<br/>
+
+<a id="what-is-kit"></a>
 ## 💡 2-Sentence Mental Model
 
+> [!TIP]
 > **Think of `jules-orchestrator-kit` as an automated Engineering Manager for AI coding agents.**  
-> **It hands out clear tasks, runs your tests in an isolated sandbox, fixes broken code automatically, and only opens a Pull Request when 100% of your tests pass.**
+> It hands out clear tasks, runs your tests in an isolated sandbox, fixes broken code automatically, and only opens a Pull Request when 100% of your tests pass.
+
+<br/>
 
 ---
 
+<br/>
+
 ## 🎯 Why `jules-orchestrator-kit`?
 
 Autonomous coding agents can write software at 100× human speed—but unconstrained agents introduce silent regressions, leak API keys, hallucinate test assertions, and thrash shared monorepos.
 
 `jules-orchestrator-kit` provides the missing **Safety, Orchestration, and Verification Kernel** for high-reliability AI agent deployments:
-- **🔒 Zero Runtime Dependencies:** Built exclusively on Node.js 20+ built-ins (`node:fs`, `node:child_process`, `node:crypto`, `node:path`, `node:test`). Zero third-party npm packages mean zero supply-chain CVE risk.
-- **🛡️ Fail-Closed Security Gatekeeper:** Unconditionally evaluates explicit Deny rules *before* Allow rules, redacts high-entropy secrets and PII from dry-runs and git diffs, and rejects PRs exceeding the 75 KB Diff Payload governor.
-- **🔄 Autonomous OODA Self-Healing:** Captures test stderr/stdout, normalizes failure fingerprints, and feeds structured error contexts back into repair iterations (up to 3 automatic attempts) before human escalation.
-- **🌐 Universal Polyglot Spine:** Natively auto-detects 24+ tech stacks (PHP/Laravel/WordPress, .NET/C#, Python, Go, Rust, C/C++, Flutter/Swift, Node/Deno/Bun) and transparently wraps verification suites in Docker Compose or Devcontainer sandboxes.
-- **📂 Scoped Monorepo Boundary Resolver:** Statically maps changed files up directory ancestry to invoke isolated subshell test suites (`(cd backend && pytest) && (cd cli && cargo test)`), eliminating global test thrashing.
-- **🚀 Zero-Test Bootstrapping (`agentctl bootstrap`):** Synthesizes deterministic syntax-check and smoke-test verification oracles for untested legacy repositories so agents always operate against a falsifiable feedback loop.
-- **📈 Proven Scale & Reliability:** Empirically tested with **221 unit tests across 54 suites passing in < 1.2s**, supporting 300+ daily agent sessions per repository.
+
+* **🔒 Zero Runtime Dependencies:** Built exclusively on Node.js 20+ built-ins (`node:fs`, `node:child_process`, `node:crypto`, `node:path`, `node:http`, `node:test`). Zero third-party npm packages mean zero supply-chain CVE risk.
+
+* **🛡️ Fail-Closed Security Gatekeeper:** Unconditionally evaluates explicit Deny rules *before* Allow rules, redacts high-entropy secrets and PII from dry-runs and git diffs, and rejects PRs exceeding the 75 KB Diff Payload governor.
+
+* **🔄 Autonomous OODA Self-Healing:** Captures test stderr/stdout, normalizes failure fingerprints, and feeds structured error contexts back into repair iterations (up to 3 automatic attempts) before human escalation.
+
+* **🌐 Universal Polyglot Spine:** Natively auto-detects 24+ tech stacks (PHP/Laravel/WordPress, .NET/C#, Python, Go, Rust, C/C++, Flutter/Swift, Node/Deno/Bun) and transparently wraps verification suites in Docker Compose or Devcontainer sandboxes.
+
+* **📂 Scoped Monorepo Boundary Resolver:** Statically maps changed files up directory ancestry to invoke isolated subshell test suites (`(cd backend && pytest) && (cd cli && cargo test)`), eliminating global test thrashing.
+
+* **🚀 Zero-Test Bootstrapping (`agentctl bootstrap`):** Synthesizes deterministic syntax-check and smoke-test verification oracles for untested legacy repositories so agents always operate against a falsifiable feedback loop.
+
+* **📈 Proven Scale & Reliability:** Empirically tested with **224 unit tests across 55 suites passing in < 1.2s**, supporting 300+ daily agent sessions per repository.
+
+<br/>
 
 ---
 
+<br/>
+
+<a id="triage-guidelines"></a>
 ## 🎯 Triage Guidelines: When to Use vs. When NOT to Use
 
 To ensure maximum merge success, dispatch tasks according to our deterministic triage boundaries:
 
+<br/>
+
 ### 🟢 Ideal Tasks for Autonomous Swarms
-- ✅ **Scoped Code Changes & Bug Fixes:** Well-defined objectives mechanically verifiable via unit tests (`npm test`, `pytest`, `cargo test`, `dotnet test`).
-- ✅ **Type & Linter Migrations:** TypeScript strict mode fixes, PHP 8.3 type hint additions, or Python MyPy type annotation passes.
-- ✅ **Dependency Bumps & Security Audits:** Remediating CVEs in lockfiles (`package.json`, `Cargo.toml`, `composer.json`) with hermetic test verification.
-- ✅ **Refactoring Legacy Codebases:** Modularizing backend routes, API controllers, or database query layers.
-- ✅ **Visual & E2E Testing (via Playwright):** UI changes paired with automated headless Playwright snapshot tests (`npx playwright test`).
+
+* ✅ **Scoped Code Changes & Bug Fixes:** Well-defined objectives mechanically verifiable via unit tests (`npm test`, `pytest`, `cargo test`, `dotnet test`).
+* ✅ **Type & Linter Migrations:** TypeScript strict mode fixes, PHP 8.3 type hint additions, or Python MyPy type annotation passes.
+* ✅ **Dependency Bumps & Security Audits:** Remediating CVEs in lockfiles (`package.json`, `Cargo.toml`, `composer.json`) with hermetic test verification.
+* ✅ **Refactoring Legacy Codebases:** Modularizing backend routes, API controllers, or database query layers.
+* ✅ **Visual & E2E Testing (via Playwright):** UI changes paired with automated headless Playwright snapshot tests (`npx playwright test`).
+
+<br/>
 
 ### 🔴 When NOT to Use (Out of Scope)
-- ❌ **Unverifiable Visual UI Tweaks:** Pixel-perfect CSS/Tailwind adjustments lacking automated visual regression tests (agents cannot "see" raw browser output without Playwright).
-- ❌ **Closed Proprietary Platforms Without CLI:** Systems lacking local CLI tools or git repositories (e.g., Salesforce, Webflow, closed SAP backends).
-- ❌ **Unmocked Live Cloud Systems:** Code requiring live connections to 10+ external cloud APIs without local emulators or mocks.
-- ❌ **Protected Infrastructure Paths:** Direct edits to `.github/workflows/`, production deployment keys, or agent security gate rules (enforced fail-closed by `Agent Scope Guard`).
+
+* ❌ **Unverifiable Visual UI Tweaks:** Pixel-perfect CSS/Tailwind adjustments lacking automated visual regression tests (agents cannot "see" raw browser output without Playwright).
+* ❌ **Closed Proprietary Platforms Without CLI:** Systems lacking local CLI tools or git repositories (e.g., Salesforce, Webflow, closed SAP backends).
+* ❌ **Unmocked Live Cloud Systems:** Code requiring live connections to 10+ external cloud APIs without local emulators or mocks.
+* ❌ **Protected Infrastructure Paths:** Direct edits to `.github/workflows/`, production deployment keys, or agent security gate rules (enforced fail-closed by `Agent Scope Guard`).
+
+<br/>
 
 ---
 
+<br/>
+
+<a id="matrix"></a>
 ## 📊 Feature Comparison Matrix
 
-| Dimension | Raw Agent Execution (No Orchestrator) | Standard CI/CD Pipelines | `jules-orchestrator-kit` (v0.26+) |
+| Dimension | Raw Agent Execution (No Orchestrator) | Standard CI/CD Pipelines | `jules-orchestrator-kit` (v0.27+) |
 | :--- | :--- | :--- | :--- |
 | **Self-Healing Loop** | ❌ None (Crashes on test error) | ❌ None (Fails build; notifies human) | ✅ **Autonomous OODA Loop** (Max 3 repair turns with error fingerprinting) |
 | **Scope Isolation** | ❌ None (Can modify CI files or lockfiles) | 🟡 Post-commit branch rules only | ✅ **Fail-Closed Scope Guard** (Deny-first evaluation; blocks protected paths) |
@@ -84,12 +123,19 @@ To ensure maximum merge success, dispatch tasks according to our deterministic t
 | **Secret Leak Prevention**| ❌ Prone to leaking tokens in diffs | 🟡 Post-push secret scanning alerts | ✅ **Pre-Dispatch & Pre-Commit Diff Scanner** (Blocks CVEs/keys before PR creation) |
 | **Dependency Footprint** | ❌ Requires heavy SDKs & parsers | 🟡 Many external actions & plugins | ✅ **0 Native Dependencies** (100% Node.js 20+ ESM built-ins) |
 
+<br/>
+
 ---
 
+<br/>
+
+<a id="quickstart"></a>
 ## ⚡ Universal 30-Second Quickstart (Zero to Verified PR)
 
 Get from zero to an autonomously verified GitHub Pull Request across any software ecosystem in 30 seconds.
 
+<br/>
+
 ### 1️⃣ Node.js / TypeScript (npm, pnpm, yarn, bun, deno)
 ```bash
 # Dispatch a scoped task; auto-detects package.json / tsconfig.json and runs type-checked tests
@@ -97,6 +143,8 @@ npx jules-orchestrator-kit dispatch --title "Add rate limiting to API router" \
   --prompt "Implement IP-based token-bucket rate limiting in src/router.ts with unit tests."
 ```
 
+<br/>
+
 ### 2️⃣ Python / FastAPI / Django (pytest, pyproject.toml)
 ```bash
 # Bootstrap zero-test or legacy Python repo, then dispatch task
@@ -105,6 +153,8 @@ npx jules-orchestrator-kit dispatch --title "Add OAuth2 JWT validation" \
   --prompt "Add JWT bearer authentication middleware to backend/api/auth.py and verify via pytest."
 ```
 
+<br/>
+
 ### 3️⃣ PHP / Laravel / WordPress (Docker Compose + PHPUnit/Pest)
 ```bash
 # Auto-detects docker-compose.yml and wraps test commands in `docker compose exec -T app ...`
@@ -112,6 +162,8 @@ npx jules-orchestrator-kit dispatch --title "Upgrade PHP 8.3 type annotations" \
   --prompt "Add strict type hints to all repository classes in app/Repositories/."
 ```
 
+<br/>
+
 ### 4️⃣ .NET / C# Enterprise (*.sln, *.csproj)
 ```bash
 # Auto-detects .sln / .csproj and runs `dotnet test --no-restore --nologo`
@@ -119,6 +171,8 @@ npx jules-orchestrator-kit dispatch --title "Implement OrderService caching" \
   --prompt "Add IMemoryCache caching to OrderService.cs with xUnit coverage."
 ```
 
+<br/>
+
 ### 5️⃣ UI / Frontend E2E (Playwright)
 ```bash
 # Dispatch frontend task verified via headless Playwright E2E tests
@@ -126,88 +180,109 @@ npx jules-orchestrator-kit dispatch --title "Add Dark Mode Toggle Component" \
   --prompt "Create ThemeToggle component in src/components/ThemeToggle.tsx and verify via npx playwright test."
 ```
 
+<br/>
+
 ### 6️⃣ Polyglot Monorepo (FastAPI + React + Rust CLI)
 ```bash
 # Run a parallel worktree swarm; changed files automatically route to scoped subproject tests
 npx jules-orchestrator-kit swarm
 ```
 
+<br/>
+
+<details>
+<summary><b>🔍 View All 24+ Supported Ecosystems & Stack Triggers</b></summary>
+
+<br/>
+
+```
+Ecosystems Natively Supported by src/stack-detector.mjs:
+├── PHP / Laravel / WordPress (composer.json, phpunit.xml, pest.php, artisan, wp-cli.yml)
+├── .NET / C# / F# (*.sln, *.csproj, *.fsproj, global.json)
+├── Mobile / Dart / Flutter (pubspec.yaml)
+├── Mobile / Swift / Xcode (Package.swift)
+├── Mobile / React Native (app.json, react-native.config.js)
+├── Systems / CMake (CMakeLists.txt)
+├── Systems / Rust Cargo (Cargo.toml)
+├── Systems / Go (go.mod)
+├── Systems / Make (Makefile)
+├── Python / FastAPI / Django (pyproject.toml, requirements.txt, setup.py)
+├── Elixir / Phoenix (mix.exs)
+├── Ruby / Rails (Gemfile)
+├── Java / Maven (pom.xml)
+├── Java / Gradle (build.gradle, build.gradle.kts)
+├── JS / TS Workspaces (turbo.json, pnpm-workspace.yaml, nx.json)
+├── JS / TS Runtimes (bunfig.toml, deno.json, package.json)
+└── Devcontainers & Docker Compose (.devcontainer/devcontainer.json, docker-compose.yml, Dockerfile)
+```
+
+</details>
+
+<br/>
+
 ---
 
+<br/>
+
+<a id="architecture"></a>
 ## 🏛️ System Architecture & Visual Diagrams
 
+<br/>
+
 ### 1. The Autonomous OODA Verification Loop
 Every task dispatched to `jules-orchestrator-kit` executes within an immutable, fail-closed verification loop:
 
+```mermaid
+flowchart TD
+    A["📩 Task Envelope"] --> B["1. Validate Scope & Base Freshness"]
+    B --> C["2. Create Isolated Git Worktree & VFS Lock"]
+    C --> D["3. Dispatch Task to Google Jules / LLM"]
+    D --> E["4. Execute Scoped Verification Gate<br/><code>detectPolyglotStack().testCmd</code>"]
+    
+    E -->|PASS| F["5. Security Audit<br/><i>Redact Secrets, Diff < 75KB</i>"]
+    F --> G["7. Rebase & Open PR<br/><code>git rebase main && gh pr create</code>"]
+
+    E -->|FAIL| H["6. Fingerprint Stderr & Flaky Verdict"]
+    H -->|Oscillation >= 0.40| I["🚨 Quarantined Test<br/><i>Exit Code 8</i>"]
+    H -->|Normal Failure| J["🔄 Attempt OODA Repair Turn<br/><i>Max 3 Retries; Exit 4 on Exhaust</i>"]
+    J --> D
 ```
-+---------------------------------------------------------------------------------------------------+
-|                           AUTONOMOUS OODA SELF-HEALING ENGINE (v0.26+)                            |
-|                                                                                                   |
-|  [Task Envelope] --> (1. Validate Scope & Base Freshness)                                         |
-|                             |                                                                     |
-|                             v                                                                     |
-|                      (2. Create Isolated Git Worktree / VFS Lock)                                 |
-|                             |                                                                     |
-|                             v                                                                     |
-|                      (3. Dispatch AI Task to Google Jules / LLM)                                  |
-|                             |                                                                     |
-|                             v                                                                     |
-|                      (4. Execute Scoped Verification Gate)                                        |
-|                          -- detectPolyglotStack().testCmd                                         |
-|                          -- Docker Compose / Devcontainer wrapper                                 |
-|                             |                                                                     |
-|                   +---------+---------+                                                           |
-|                   | PASS              | FAIL                                                      |
-|                   v                   v                                                           |
-|         (5. Security Audit)   (6. Fingerprint Stderr / Flaky Verdict)                             |
-|           - Redact Secrets        |                                                               |
-|           - Check Diff < 75KB     +---> Is test QUARANTINED? (Oscillation >= 0.40)                |
-|                   |                     |                         |                               |
-|                   v                    YES                        NO                              |
-|         (7. Rebase & PR)                |                         |                               |
-|           - git rebase main             v                         v                               |
-|           - gh pr create      [Log Quarantined Flake]   [Attempt OODA Repair Turn]                |
-|                               (Exit Code 8)             (Max 3 Retries; Exit 4 on Exhaust)        |
-+---------------------------------------------------------------------------------------------------+
-```
+
+<br/>
 
 ### 2. Polyglot Monorepo Scoped Execution Engine
 In monorepos containing multiple languages, `resolveWorkspaceBoundary(changedFiles)` traverses directory ancestry to isolate verification to affected subprojects:
 
+```mermaid
+flowchart TD
+    A["📁 Changed Files<br/><code>['backend/api/main.py', 'cli/src/main.rs']</code>"] --> B{"Check Shared Triggers?<br/><i>docker-compose.yml, openapi.yaml</i>"}
+    B -->|None Changed| C["Traverse Directory Ancestry"]
+    C --> D1["<code>backend/api/main.py</code> → <code>backend/pyproject.toml</code><br/><i>(Python Stack)</i>"]
+    C --> D2["<code>cli/src/main.rs</code> → <code>cli/Cargo.toml</code><br/><i>(Rust Stack)</i>"]
+    D1 --> E["Synthesize POSIX Subshell Verification Plan<br/><code>(cd backend && pytest) && (cd cli && cargo test)</code>"]
+    D2 --> E
 ```
-+---------------------------------------------------------------------------------------------------+
-|                        MONOREPO BOUNDARY RESOLVER (resolveWorkspaceBoundary)                      |
-|                                                                                                   |
-|  changedFiles: ["backend/api/main.py", "cli/src/main.rs", "docs/README.md"]                      |
-|         |                                                                                         |
-|         +---> 1. Check Root Shared Triggers (openapi.yaml, docker-compose.yml, Makefile)          |
-|         |        -> None changed. Continue subproject isolation.                                  |
-|         |                                                                                         |
-|         +---> 2. Map Files to Subproject Roots by Trigger File Traversal:                         |
-|         |        - "backend/api/main.py" -> backend/pyproject.toml (Python Stack)                 |
-|         |        - "cli/src/main.rs"     -> cli/Cargo.toml (Rust/Cargo Stack)                     |
-|         |        - "docs/README.md"      -> (Documentation; R0 Cosmetic Risk)                     |
-|         |                                                                                         |
-|         +---> 3. Synthesize Scoped POSIX Subshell Verification Plan:                              |
-|                  testCmd:  "(cd backend && pytest) && (cd cli && cargo test --workspace)"         |
-|                  buildCmd: "(cd cli && cargo build)"                                              |
-|                                                                                                   |
-|  Result: 100% test isolation, 0 global test thrashing, 0 git index lock collisions.               |
-+---------------------------------------------------------------------------------------------------+
-```
+
+<br/>
 
 ---
 
+<br/>
+
+<a id="cli-docs"></a>
 ## 🛠️ CLI Command Reference (`agentctl`)
 
 `agentctl` is the unified command-line interface for `jules-orchestrator-kit`, available via `bin/agentctl.mjs` or `npx jules-orchestrator-kit <command>`.
 
+<br/>
+
 | Command | Usage | Description | Exit Codes |
 | :--- | :--- | :--- | :--- |
 | `dispatch` | `agentctl dispatch --title <t> --prompt <p>` | Dispatches a single task to an AI agent in an isolated worktree. | `0` (Success), `1` (Arg error), `2` (429 Rate limit), `3` (Scope deny), `4` (OODA exhausted), `5` (Diff > 75KB), `6` (Secret leak) |
+| `review-repair`| `agentctl review-repair <pr-comments.json>`| Parses GitHub PR review comments and synthesizes actionable OODA repair tasks. | `0` (Parsed), `1` (Missing file) |
+| `dashboard` | `agentctl dashboard [port]` | Starts zero-dependency local HTTP telemetry and audit visualizer dashboard. | `0` (Running) |
 | `gate` / `audit`| `agentctl gate --base main --json` | Runs security, secret scanning, and verification gate against current branch. | `0` (Approved), `3` (Scope violation), `5` (Diff limit), `6` (Secret leak) |
 | `bootstrap` | `agentctl bootstrap [--force] [--json]` | Inspects an untested repository and synthesizes `.agent/config.yml` with a zero-test verification oracle (`php -l`, `compileall`, `dotnet build`, `tsc`, `smoke`). | `0` (Bootstrapped / Existing) |
-| `review-repair`| `agentctl review-repair <pr-comments.json>`| Parses GitHub PR review comments and synthesizes actionable OODA repair tasks. | `0` (Parsed), `1` (Missing file) |
 | `queue` | `agentctl queue` | Consumes and executes pending markdown task envelopes in `.agent/queue/`. | `0` (Complete) |
 | `swarm` | `agentctl swarm` | Runs parallel multi-agent swarm across queued tasks with token-bucket concurrency. | `0` (Complete) |
 | `doctor` | `agentctl doctor` | Diagnostic inspect: displays detected stack, container wrapper, test command, and daily session budget. | `0` (Healthy) |
@@ -215,57 +290,46 @@ In monorepos containing multiple languages, `resolveWorkspaceBoundary(changedFil
 | `clean` | `agentctl clean` | Prunes stale git worktrees, lockfiles, and temporary ledgers. | `0` (Clean) |
 | `init` | `agentctl init` | Scaffolds `.agent/` directory structure and default `.agent/config.yml`. | `0` (Created) |
 | `mcp` | `agentctl mcp` | Starts stdio Model Context Protocol (MCP) server for tool integration. | `0` / Stdio stream |
-| `version` | `agentctl version` | Outputs orchestrator kit semantic version (`v0.26.1`). | `0` |
+| `version` | `agentctl version` | Outputs orchestrator kit semantic version (`v0.27.0`). | `0` |
 
----
-
-## 🌐 Universal Polyglot Support & Stack Detection
-
-The table below illustrates the 24+ software ecosystems natively supported by `src/stack-detector.mjs`:
-
-```
-Ecosystems Supported:
-├── PHP / Laravel / WordPress (composer.json, phpunit.xml, pest.php, artisan, wp-cli.yml)
-├── .NET / C# / F# (*.sln, *.csproj, *.fsproj, global.json)
-├── Mobile / Dart / Flutter (pubspec.yaml)
-├── Mobile / Swift / Xcode (Package.swift)
-├── Mobile / React Native (app.json, react-native.config.js)
-├── Systems / CMake (CMakeLists.txt)
-├── Systems / Rust Cargo (Cargo.toml)
-├── Systems / Go (go.mod)
-├── Systems / Make (Makefile)
-├── Python / FastAPI / Django (pyproject.toml, requirements.txt, setup.py)
-├── Elixir / Phoenix (mix.exs)
-├── Ruby / Rails (Gemfile)
-├── Java / Maven (pom.xml)
-├── Java / Gradle (build.gradle, build.gradle.kts)
-├── JS / TS Workspaces (turbo.json, pnpm-workspace.yaml, nx.json)
-├── JS / TS Runtimes (bunfig.toml, deno.json, package.json)
-└── Devcontainers & Docker Compose (.devcontainer/devcontainer.json, docker-compose.yml, Dockerfile)
-```
+<br/>
 
 ---
 
+<br/>
+
+<a id="roadmap"></a>
 ## 🗺️ v0.27+ Next-Gen Feature Roadmap
 
 | Feature | Module / Command | Architectural Blueprint | Target Release |
 | :--- | :--- | :--- | :---: |
-| **PR Review Auto-Remediation Loop** | `agentctl review-repair` (`src/review-repair.mjs`) | Ingests GitHub PR review comments (`CHANGES_REQUESTED`), extracts line/file context, and dispatches automated OODA repair turns until reviewer comments are resolved. | **v0.27.0** *(Implemented prototype)* |
-| **Multi-Provider Failover Router** | `createFailoverProvider` (`src/provider.mjs`) | Ordered router (`["jules", "claude-code", "local-mcp"]`) that seamlessly falls back to secondary LLMs on HTTP 429 rate limits or 5xx service unavailability. | **v0.27.0** *(Implemented prototype)* |
-| **Telemetry & Audit Web Dashboard**| `agentctl dashboard` (`src/dashboard.mjs`) | Zero-dependency local HTTP server displaying real-time DAG execution graphs, Wilson-Score flaky test ledgers, and SHA-256 telemetry chains. | **v0.27.0** |
+| **PR Review Auto-Remediation Loop** | `agentctl review-repair` (`src/review-repair.mjs`) | Ingests GitHub PR review comments (`CHANGES_REQUESTED`), extracts line/file context, and dispatches automated OODA repair turns until reviewer comments are resolved. | **v0.27.0** *(Shipped)* |
+| **Multi-Provider Failover Router** | `createFailoverProvider` (`src/provider.mjs`) | Ordered router (`["jules", "claude-code", "local-mcp"]`) that seamlessly falls back to secondary LLMs on HTTP 429 rate limits or 5xx service unavailability. | **v0.27.0** *(Shipped)* |
+| **Telemetry & Audit Web Dashboard**| `agentctl dashboard` (`src/dashboard.mjs`) | Zero-dependency local HTTP server displaying real-time DAG execution graphs, Wilson-Score flaky test ledgers, and SHA-256 telemetry chains. | **v0.27.0** *(Shipped)* |
 | **Cross-Language Contract Guard** | `hashCrossLanguageInterface` (`src/merge-blocks.mjs`)| Canonical SHA-256 schema hashing for OpenAPI/Protobuf specs across polyglot task dependencies in `DagExecutor`. | **v0.26.0** *(Shipped)* |
 
+<br/>
+
 ---
 
+<br/>
+
 ## 📖 Recipes, Documentation & Prior Art
 
+- [**Google Jules Official Documentation**](https://jules.google) — Official platform overview and API specifications for Google Jules.
+- [**Google Labs Code Repositories**](https://github.com/google-labs-code) — Official Google Labs public GitHub organization (jules-action, jules-sdk).
 - [**Universal Polyglot Architecture & Zero-Test Specification**](./docs/UNIVERSAL_POLYGLOT_ARCHITECTURE.md) — Comprehensive technical report on boundary resolution, OODA math, and B2B workflows.
+- [**v0.27.0 Architectural Audit & Platform Evolution**](./docs/V0.27_ARCHITECTURAL_AUDIT_AND_EVOLUTION.md) — PR review remediation, failover router, and local dashboard specs.
 - [**Examples & Task Envelope Recipes**](./EXAMPLES.md) — Production YAML and Markdown task envelopes.
 - [**Adversarial Security Audit Phase 4 Report**](./docs/AUDIT_REPORT.md) — CWE-77, CWE-1321, and CWE-183 security hardening analysis.
 - [**Changelog**](./CHANGELOG.md) — Full release history and migration guides.
 
+<br/>
+
 ---
 
+<br/>
+
 <div align="center">
   <p><b>jules-orchestrator-kit</b> • Built with zero external dependencies for Google Jules and enterprise AI agent swarms.</p>
 </div>

package/bin/agentctl.mjs

@@ -14,7 +14,7 @@ const command = args[0];
 
 function printHelp() {
   console.log(`
-🚀 agentctl v0.26.2 — Universal Agent Orchestrator & Safety Gatekeeper
+🚀 agentctl v0.27.1 — Universal Agent Orchestrator & Safety Gatekeeper
 
 Usage: agentctl <command> [options]
 
@@ -28,6 +28,8 @@ Commands:
   lock <action>         Manage mutex locks (acquire | release | status | cleanup)
   doctor                Run system diagnostics and stack resolution checks
   bootstrap             Bootstrap zero-test repository with verification oracle
+  review-repair         Parse PR review comments and synthesize OODA repair tasks
+  dashboard             Start local HTTP telemetry and audit dashboard
   init                  Scaffold .agent/ directory and config.yml
   version               Output agentctl version
 
@@ -45,7 +47,7 @@ async function main() {
   }
 
   if (command === "version" || command === "--version" || command === "-v") {
-    console.log("agentctl v0.26.2");
+    console.log("agentctl v0.27.0");
     process.exit(0);
   }
 
@@ -263,6 +265,31 @@ async function main() {
       break;
     }
 
+    case "review-repair": {
+      const fileArg = args[1];
+      if (!fileArg || !existsSync(fileArg)) {
+        console.error("Error: Please provide a valid JSON file containing PR review comments.");
+        process.exit(1);
+      }
+      const { parseReviewComments, createReviewRepairTask } = await import("../src/review-repair.mjs");
+      const raw = readFileSync(fileArg, "utf-8");
+      const comments = parseReviewComments(raw);
+      console.log(`✅ Parsed ${comments.length} actionable review comment(s).`);
+      for (const c of comments) {
+        const task = createReviewRepairTask(c);
+        console.log(`   Task: ${task.title} (Author: @${c.author}, Line: ${c.line || "N/A"})`);
+      }
+      process.exit(0);
+      break;
+    }
+
+    case "dashboard": {
+      const port = Number(args[1] || 4100);
+      const { startDashboardServer } = await import("../src/dashboard.mjs");
+      startDashboardServer(port, root);
+      break;
+    }
+
     case "init": {
       const agentDir = join(root, ".agent");
       ensureDir(agentDir);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jules-orchestrator-kit",
-  "version": "0.26.2",
+  "version": "0.27.1",
   "description": "Orchestration kit for running Google Jules autonomous agents.",
   "repository": {
     "type": "git",

package/src/dashboard.mjs

@@ -0,0 +1,136 @@
+/**
+ * Zero-Dependency Local Telemetry & Audit HTTP Dashboard for jules-orchestrator-kit (v0.27.0).
+ * Uses node:http to serve real-time HTML/CSS dark mode visualizer and REST JSON endpoints.
+ */
+
+import http from "node:http";
+import { readTelemetry, verifyTelemetryIntegrity } from "./telemetry.mjs";
+import { readVerifyRuns, flakyVerdict } from "./flaky-ledger.mjs";
+import { lockStatus } from "./state.mjs";
+
+export function getDashboardHtml(root = process.cwd()) {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>jules-orchestrator-kit Dashboard</title>
+  <style>
+    body { background-color: #0d1117; color: #c9d1d9; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; margin: 0; padding: 24px; }
+    h1 { color: #58a6ff; font-size: 24px; margin-bottom: 8px; }
+    .subtitle { color: #8b949e; font-size: 14px; margin-bottom: 24px; }
+    .grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(320px, 1fr)); gap: 16px; margin-bottom: 24px; }
+    .card { background: #161b22; border: 1px solid #30363d; border-radius: 8px; padding: 16px; }
+    .card h2 { font-size: 16px; color: #f0f6fc; margin-top: 0; border-bottom: 1px solid #21262d; padding-bottom: 8px; }
+    table { width: 100%; border-collapse: collapse; font-size: 13px; }
+    th, td { text-align: left; padding: 8px; border-bottom: 1px solid #21262d; }
+    th { color: #8b949e; }
+    .badge { display: inline-block; padding: 2px 8px; border-radius: 12px; font-size: 12px; font-weight: 600; }
+    .badge-success { background: rgba(46, 160, 67, 0.15); color: #3fb950; border: 1px solid rgba(46, 160, 67, 0.4); }
+    .badge-warn { background: rgba(210, 153, 34, 0.15); color: #d29922; border: 1px solid rgba(210, 153, 34, 0.4); }
+    code { font-family: monospace; background: #21262d; padding: 2px 4px; border-radius: 4px; }
+  </style>
+</head>
+<body>
+  <h1>🚀 jules-orchestrator-kit Dashboard (v0.27.0)</h1>
+  <div class="subtitle">Repository: <code>${root}</code></div>
+
+  <div class="grid">
+    <div class="card">
+      <h2>🛡️ SHA-256 Telemetry Integrity</h2>
+      <div id="telemetry-status">Loading...</div>
+    </div>
+    <div class="card">
+      <h2>⚖️ Wilson-Score Flaky Ledger</h2>
+      <div id="flaky-status">Loading...</div>
+    </div>
+    <div class="card">
+      <h2>🔒 Active VFS Mutex Locks</h2>
+      <div id="locks-status">Loading...</div>
+    </div>
+  </div>
+
+  <script>
+    async function updateDashboard() {
+      try {
+        const [telRes, flakyRes, locksRes] = await Promise.all([
+          fetch('/api/telemetry?limit=10').then(r => r.json()),
+          fetch('/api/flaky').then(r => r.json()),
+          fetch('/api/locks').then(r => r.json())
+        ]);
+
+        document.getElementById('telemetry-status').innerHTML = telRes.integrity?.valid
+          ? '<span class="badge badge-success">✓ SHA-256 Hash Chain Valid</span> <p>Events logged: ' + telRes.events.length + '</p>'
+          : '<span class="badge badge-warn">⚠ Check Telemetry Logs</span>';
+
+        document.getElementById('flaky-status').innerHTML = '<p>Verdict: <code>' + (flakyRes.verdict?.action || 'CLEAN') + '</code></p><p>Tracked test runs: ' + flakyRes.count + '</p>';
+        document.getElementById('locks-status').innerHTML = '<p>Active VFS Locks: <code>' + locksRes.count + '</code></p>';
+      } catch (err) {
+        console.error("Dashboard update failed:", err);
+      }
+    }
+    updateDashboard();
+    setInterval(updateDashboard, 5000);
+  </script>
+</body>
+</html>`;
+}
+
+export function createDashboardServer({ root = process.cwd(), port: _port = 4100 } = {}) {
+  return http.createServer((req, res) => {
+    const url = new URL(req.url || "/", `http://${req.headers.host || "localhost"}`);
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    res.setHeader("Access-Control-Allow-Methods", "GET, OPTIONS");
+
+    if (req.method === "OPTIONS") {
+      res.writeHead(204);
+      return res.end();
+    }
+
+    if (url.pathname === "/" || url.pathname === "/index.html") {
+      res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+      return res.end(getDashboardHtml(root));
+    }
+
+    if (url.pathname === "/api/status") {
+      res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
+      return res.end(JSON.stringify({ ok: true, version: "0.27.0", root, ts: new Date().toISOString() }));
+    }
+
+    if (url.pathname === "/api/telemetry") {
+      const limit = Number(url.searchParams.get("limit") || "50");
+      res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
+      return res.end(
+        JSON.stringify({
+          ok: true,
+          count: limit,
+          integrity: verifyTelemetryIntegrity(root),
+          events: readTelemetry(root, limit),
+        })
+      );
+    }
+
+    if (url.pathname === "/api/flaky") {
+      const runs = readVerifyRuns(root);
+      res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
+      return res.end(JSON.stringify({ ok: true, count: runs.length, verdict: flakyVerdict(runs), runs }));
+    }
+
+    if (url.pathname === "/api/locks") {
+      const locks = lockStatus(root);
+      res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
+      return res.end(JSON.stringify({ ok: true, count: locks.length, locks }));
+    }
+
+    res.writeHead(404, { "Content-Type": "application/json; charset=utf-8" });
+    res.end(JSON.stringify({ ok: false, error: "Not Found", path: url.pathname }));
+  });
+}
+
+export function startDashboardServer(port = 4100, root = process.cwd()) {
+  const server = createDashboardServer({ root, port });
+  server.listen(port, "0.0.0.0", () => {
+    console.log(`🚀 jules-orchestrator-kit Dashboard running at http://localhost:${port}`);
+  });
+  return server;
+}

package/src/git.mjs

@@ -1,6 +1,6 @@
 import { execFileSync } from "node:child_process";
 import { normalizePath } from "./config.mjs";
-import { journalIntent, journalDone } from "./journal.mjs";
+
 
 export const NET_GUARD_PRELOAD_URL = new URL("./preload-net-guard.mjs", import.meta.url).href;
 export const NET_GUARD_FLAG = `--import ${NET_GUARD_PRELOAD_URL}`;
@@ -173,29 +173,6 @@ export function showFromOrigin(root = process.cwd(), base = "main", filePath = "
   }
 }
 
-export function createBranch(root = process.cwd(), branch = "") {
-  const opId = journalIntent(root, { type: "create_branch", branch, targetPath: "" });
-  try {
-    const res = git(["branch", branch], { cwd: root });
-    journalDone(root, opId);
-    return res;
-  } catch (err) {
-    journalDone(root, opId);
-    throw err;
-  }
-}
-
-export function worktreeAdd(root = process.cwd(), branch = "agent/task", targetDir = "") {
-  const opId = journalIntent(root, { type: "worktree_add", targetPath: targetDir, branch });
-  try {
-    const res = git(["worktree", "add", targetDir, "-b", branch], { cwd: root });
-    journalDone(root, opId);
-    return res;
-  } catch (err) {
-    journalDone(root, opId);
-    throw err;
-  }
-}
 
 export function worktreeRemove(root = process.cwd(), targetDir = "") {
   return git(["worktree", "remove", targetDir, "--force"], { cwd: root });

package/src/provider.mjs

@@ -218,7 +218,6 @@ export function createProvider(spec = "jules", config = {}) {
         const rawArgs = providerSpec.args || (providerSpec.command ? providerSpec.command.split(" ").slice(1) : []);
         const command = providerSpec.command ? providerSpec.command.split(" ")[0] : "claude";
 
-        // CRITICAL H-a FIX: Filter out '{prompt}' argument if prompt is passed via stdin
         const filteredArgs = providerSpec.promptViaStdin
           ? rawArgs.filter((arg) => !arg.includes("{prompt}"))
           : rawArgs;
@@ -228,7 +227,7 @@ export function createProvider(spec = "jules", config = {}) {
         const res = spawnSync(command, processedArgs, {
           cwd: config._root || process.cwd(),
           encoding: "utf-8",
-          shell: false, // CRITICAL: Ban shell execution to eliminate CWE-77
+          shell: false,
           input: providerSpec.promptViaStdin ? data.prompt : undefined,
           timeout: providerSpec.timeoutMs || 900000,
           maxBuffer: 32 * 1024 * 1024,
@@ -259,3 +258,44 @@ export function createProvider(spec = "jules", config = {}) {
     },
   };
 }
+
+/**
+ * Creates a failover provider router that attempts dispatches sequentially across an ordered array of providers.
+ * Intercepts rate limits (429) and 5xx unavailability, logging telemetry events before falling over.
+ */
+export function createFailoverProvider(providers = ["jules"], config = {}) {
+  const providerList = (Array.isArray(providers) && providers.length > 0 ? providers : ["jules"]).map((spec) =>
+    spec && typeof spec === "object" && typeof spec.dispatch === "function" ? spec : createProvider(spec, config)
+  );
+
+  return {
+    name: `failover:${providerList.map((p) => p.name).join("->")}`,
+
+    async dispatch(task, ctx = {}) {
+      const errors = [];
+      for (let i = 0; i < providerList.length; i++) {
+        const provider = providerList[i];
+        try {
+          const res = await provider.dispatch(task, ctx);
+          return { ...res, _routedProvider: provider.name, _failoverAttempts: i };
+        } catch (err) {
+          errors.push({ provider: provider.name, error: err });
+          const isRecoverable =
+            err instanceof ProviderRateLimitError ||
+            err instanceof ProviderUnavailableError ||
+            (err.status && err.status >= 500 && err.status < 600) ||
+            err.status === 429;
+
+          if (i === providerList.length - 1 || !isRecoverable) {
+            err._failoverErrors = errors;
+            throw err;
+          }
+        }
+      }
+    },
+
+    validate() {
+      return providerList.every((p) => p.validate());
+    },
+  };
+}

package/src/review-repair.mjs

@@ -0,0 +1,53 @@
+/**
+ * PR Review Auto-Remediation Engine for jules-orchestrator-kit (v0.27.0).
+ * Parses GitHub PR review comments, filters conversational praise/noise,
+ * and synthesizes actionable OODA repair task envelopes.
+ */
+
+export function parseReviewComments(input) {
+  let comments = typeof input === "string" ? (() => { try { return JSON.parse(input); } catch { return []; } })() : input;
+  comments = Array.isArray(comments) ? comments : comments?.comments || comments?.reviews || [comments];
+
+  const actionable = [];
+  let idx = 0;
+  for (const c of comments) {
+    if (!c || typeof c !== "object") continue;
+
+    const state = String(c.state || c.status || "").toUpperCase();
+    if (state === "APPROVED" || state === "DISMISSED" || c.isResolved === true || c.resolved === true) continue;
+
+    const body = String(c.body || c.comment || "").trim();
+    if (body.length < 5) continue;
+
+    const praiseRegex = /^(?:lgtm|looks good(?: to me)?|nice|awesome|thanks|thank you|great work|approved|ship it)[\s.!]*$/i;
+    if (praiseRegex.test(body)) continue;
+
+    idx++;
+    const path = c.path || c.file || null;
+    const line = c.line || c.original_line || null;
+    const author = c.user?.login || c.author || "reviewer";
+
+    actionable.push({
+      id: String(c.id || `review-${idx}`),
+      path,
+      line: line ? Number(line) : null,
+      author,
+      body,
+      actionable: true,
+      prompt: `Fix PR review comment by @${author} on ${path || "code"}${line ? ` line ${line}` : ""}:\n\n"${body}"\n\nEnsure all unit tests and safety gates pass cleanly after applying fix.`,
+    });
+  }
+
+  return actionable;
+}
+
+export function createReviewRepairTask(comment, baseBranch = "main") {
+  return {
+    id: `repair-${comment.id}`,
+    title: `PR Review Repair: ${comment.path || "code"} (${comment.id})`,
+    prompt: comment.prompt || `Fix review feedback: ${comment.body}`,
+    baseBranch,
+    targetFiles: comment.path ? [comment.path] : [],
+    metadata: { source: "pr-review", commentId: comment.id, author: comment.author, line: comment.line },
+  };
+}

package/src/process-group.mjs

@@ -1,80 +0,0 @@
-import { spawn } from "node:child_process";
-
-/**
- * ProcessGroupManager manages child processes in isolated process groups
- * and ensures 100% leak-free cleanup on process exit or termination signals.
- */
-export class ProcessGroupManager {
-  constructor() {
-    this.activePgids = new Set();
-    this.activePids = new Set();
-    this.installed = false;
-    this.installSignalHandlers();
-  }
-
-  installSignalHandlers() {
-    if (this.installed) return;
-    this.installed = true;
-
-    const cleanup = (signal) => {
-      this.killAll(signal || "SIGTERM");
-    };
-
-    process.once("SIGINT", () => {
-      cleanup("SIGINT");
-      process.exit(130);
-    });
-
-    process.once("SIGTERM", () => {
-      cleanup("SIGTERM");
-      process.exit(143);
-    });
-
-    process.once("exit", () => {
-      this.killAll("SIGKILL");
-    });
-  }
-
-  spawnProcess(command, args = [], options = {}) {
-    const opts = {
-      ...options,
-      detached: true,
-    };
-
-    const child = spawn(command, args, opts);
-
-    if (child.pid) {
-      const pgid = child.pid;
-      this.activePgids.add(pgid);
-      this.activePids.add(child.pid);
-
-      child.on("exit", () => {
-        this.activePgids.delete(pgid);
-        this.activePids.delete(child.pid);
-      });
-
-      child.on("error", () => {
-        this.activePgids.delete(pgid);
-        this.activePids.delete(child.pid);
-      });
-    }
-
-    return child;
-  }
-
-  killAll(signal = "SIGTERM") {
-    for (const pgid of this.activePgids) {
-      try {
-        process.kill(-pgid, signal);
-      } catch (_) {
-        try {
-          process.kill(pgid, signal);
-        } catch (_) {}
-      }
-    }
-    this.activePgids.clear();
-    this.activePids.clear();
-  }
-}
-
-export const processGroupManager = new ProcessGroupManager();