jules-orchestrator-kit 0.29.1 → 0.31.0

package/README.md

@@ -23,12 +23,15 @@
 
 <p align="center">
   <a href="#what-is-kit">💡&nbsp;What&nbsp;is&nbsp;Kit?</a> &nbsp;•&nbsp;
+  <a href="#who-is-it-for">👥&nbsp;Who&nbsp;Is&nbsp;It&nbsp;For?</a> &nbsp;•&nbsp;
   <a href="#quickstart">⚡&nbsp;Quickstart</a> &nbsp;•&nbsp;
-  <a href="#triage-guidelines">🎯&nbsp;Triage&nbsp;Guidelines</a> &nbsp;•&nbsp;
+  <a href="#triage-guidelines">🎯&nbsp;Triage</a> &nbsp;•&nbsp;
   <a href="#matrix">📊&nbsp;Matrix</a>
   <br/>
+  <a href="#configuration">⚙️&nbsp;Configuration</a> &nbsp;•&nbsp;
   <a href="#architecture">🏛️&nbsp;Architecture</a> &nbsp;•&nbsp;
   <a href="#cli-docs">🛠️&nbsp;CLI&nbsp;Docs</a> &nbsp;•&nbsp;
+  <a href="#providers">🔌&nbsp;Providers</a> &nbsp;•&nbsp;
   <a href="#roadmap">🗺️&nbsp;Roadmap</a>
 </p>
 
@@ -59,25 +62,59 @@
 
 <br/>
 
+<a id="who-is-it-for"></a>
+## 👥 Who Is It For?
+
+Whether you are trying your first AI coding session or running enterprise monorepo swarms, `jules-orchestrator-kit` scales with your workflow:
+
+<br/>
+
+| Role | Primary Value Proposition | Key Commands |
+| :--- | :--- | :--- |
+| **🌱 Beginners & Solo Developers** | Safely experiment with AI agents without risking broken code, leaked API keys, or ruined git history. | `agentctl init`<br/>`agentctl task create` |
+| **📦 Single-Repo Maintainers** | Automate bug fixes, dependency updates, and PR reviews with automated OODA test verification. | `agentctl gate`<br/>`agentctl queue` |
+| **🏗️ Monorepo Engineering Teams** | Isolate subproject verification (`backend/`, `frontend/`, `cli/`) so agent edits never thrash global test suites. | `agentctl swarm`<br/>`agentctl lock` |
+| **🛡️ Platform & Security Engineers** | Enforce zero-trust security policies, pre-commit secret scrubbing, and strict 75 KB diff payload limits. | `agentctl doctor`<br/>`agentctl dashboard` |
+
+<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:http`, `node:test`). Zero third-party npm packages mean zero supply-chain CVE risk.
+* **🔥 Warm Multi-Turn Session Resumption (`v0.31.0`):** Streams OODA repair prompts directly into active Google Jules session streams via `POST /v1alpha/sessions/{id}:sendMessage`, saving 60–80% context tokens while preserving reasoning context.
+
+* **🧪 Automated TDD Red-to-Green Harness (`agentctl test-gen`):** Scaffolds falsifiable unit tests from bug specs, verifies **RED** failure state, locks the test file in `scope.deny`, and tasks Jules with making it pass (**GREEN** state).
+
+* **🛡️ 1-Click Atomic Git Checkpoint & Rollback (`agentctl rollback`):** Snapshots working tree state, git diffs, and stashes before every session, enabling instant 1-command git restoration.
+
+* **🌐 Verification Sandbox & SSR Hydration Prober (`verify.server`):** Executes deterministic `setup`/`teardown` hooks for databases and boots dev servers to intercept React/Next.js SSR hydration panics before approving PRs.
+
+* **⚡ AST Blast-Radius Selective Testing:** Traverses file import dependency graphs to execute only affected downstream test suites, cutting monorepo test latency from minutes to milliseconds.
+
+* **🚨 Asynchronous HITL Escalation Bridge (`agentctl escalate`):** Dispatches Slack & Discord webhook alerts when Jules needs feedback, allowing engineers to unblock agents asynchronously via `agentctl resume <id> --response "<reply>"`.
+
+* **🔒 Zero Runtime Dependencies:** Built exclusively on Node.js 20+ built-ins (`node:fs`, `node:child_process`, `node:crypto`, `node:path`, `node:http`, `node:tty`, `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.
 
+* **💻 Native Interactive UX & Command Palette (`v0.30.0`):** Features a zero-dependency full-screen Terminal Engine (`capabilities`, `key-decoder`, `renderer`, `layout`, `widgets`), interactive diagnostic matrix (`agentctl doctor`), task queue/swarm managers (`agentctl queue`, `agentctl swarm`), and a searchable Command Palette.
+
 * **🌐 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.
+* **📈 Proven Scale & Reliability:** Empirically tested with **368 unit tests across 52 suites passing in < 3.0s**, supporting 300+ daily agent sessions per repository.
 
 <br/>
 
@@ -124,11 +161,12 @@ To ensure maximum merge success, dispatch tasks according to our deterministic t
 <a id="matrix"></a>
 ## 📊 Feature Comparison Matrix
 
-| Dimension | Raw Agent Execution (No Orchestrator) | Standard CI/CD Pipelines | `jules-orchestrator-kit` (v0.27+) |
+| Dimension | Raw Agent Execution (No Orchestrator) | Standard CI/CD Pipelines | `jules-orchestrator-kit` (v0.30.0) |
 | :--- | :--- | :--- | :--- |
 | **Self-Healing Loop** | ❌ None (Crashes on test error) | ❌ None (Fails build; notifies human) | ✅ **Autonomous OODA Loop** (Max 3 repair turns with error fingerprinting) |
+| **Interactive UX Engine**| ❌ Raw unformatted CLI dumps | ❌ Non-interactive log outputs | ✅ **Native TUI Engine & Command Palette** (Zero-dependency alternate-screen TUI) |
 | **Scope Isolation** | ❌ None (Can modify CI files or lockfiles) | 🟡 Post-commit branch rules only | ✅ **Fail-Closed Scope Guard** (Deny-first evaluation; blocks protected paths) |
-| **Polyglot Stack Detection**| ❌ Manual prompt instructions | 🟡 Hardcoded YAML workflow steps | ✅ **Universal 24+ Stack Detector** (`src/stack-detector.mjs`) |
+| **Polyglot Stack Detection**| ❌ Manual prompt instructions | 🟡 Hardcoded YAML workflow steps | ✅ **Universal 24+ Stack Detector** (`src/config.mjs`) |
 | **Flaky Test Quarantine** | ❌ Fails session randomly | ❌ Breaks CI pipeline randomly | ✅ **Wilson-Score Statistical Quarantine** (Oscillation ≥ 0.40 quarantined automatically) |
 | **Monorepo Scoping** | ❌ Runs full global test suite | 🟡 Requires custom Nx/Turbo scripting | ✅ **Scoped Subshell Boundary Resolver** (`resolveWorkspaceBoundary`) |
 | **Zero-Test Bootstrapping**| ❌ Halts without verification oracle | ❌ Fails build if no tests exist | ✅ **Instant Oracle Synthesis** (`php -l`, `compileall`, `dotnet build`, `tsc`, `smoke`) |
@@ -148,62 +186,42 @@ To ensure maximum merge success, dispatch tasks according to our deterministic t
 <br/>
 
 <a id="quickstart"></a>
-## ⚡ Universal 30-Second Quickstart (Zero to Verified PR)
+## ⚡ Guided Quickstart (Audit → Author → Verify)
 
-Get from zero to an autonomously verified GitHub Pull Request across any software ecosystem in 30 seconds.
+Get started with a safe 3-step workflow across any repository:
 
 <br/>
 
-### 1️⃣ Node.js / TypeScript (npm, pnpm, yarn, bun, deno)
+### Step 1: Security & Scope Gate Audit
+Audit your current working tree or branch for secret leaks, protected path violations, and verification readiness:
 ```bash
-# Dispatch a scoped task; auto-detects package.json / tsconfig.json and runs type-checked tests
-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."
+# Run security, secret scanning, and scope gate audit without modifying files
+npx jules-orchestrator-kit gate --mode working-tree
 ```
 
 <br/>
 
-### 2️⃣ Python / FastAPI / Django (pytest, pyproject.toml)
+### Step 2: Author a Scoped Task
+Launch the interactive task authoring wizard or create a task via CLI:
 ```bash
-# Bootstrap zero-test or legacy Python repo, then dispatch task
-npx jules-orchestrator-kit bootstrap --force
-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/>
+# Interactive authoring wizard with secret scrubbing & verification probes
+npx jules-orchestrator-kit task create
 
-### 3️⃣ PHP / Laravel / WordPress (Docker Compose + PHPUnit/Pest)
-```bash
-# Auto-detects docker-compose.yml and wraps test commands in `docker compose exec -T app ...`
-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`
-npx jules-orchestrator-kit dispatch --title "Implement OrderService caching" \
-  --prompt "Add IMemoryCache caching to OrderService.cs with xUnit coverage."
+# Or dispatch directly with explicit flags
+npx jules-orchestrator-kit task create --title "Fix authentication token expiration" \
+  --prompt "Fix JWT expiration check in src/auth.mjs and verify with npm test."
 ```
 
 <br/>
 
-### 5️⃣ UI / Frontend E2E (Playwright)
+### Step 3: Local Verification & Queue Execution
+Inspect diagnostics and execute queued tasks:
 ```bash
-# Dispatch frontend task verified via headless Playwright E2E tests
-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/>
+# Run interactive diagnostic matrix
+npx jules-orchestrator-kit doctor --interactive
 
-### 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
+# Process pending task queue in isolated worktrees
+npx jules-orchestrator-kit queue --interactive
 ```
 
 <br/>
@@ -214,7 +232,7 @@ npx jules-orchestrator-kit swarm
 <br/>
 
 ```
-Ecosystems Natively Supported by src/stack-detector.mjs:
+Ecosystems Natively Supported by src/config.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)
@@ -242,6 +260,46 @@ Ecosystems Natively Supported by src/stack-detector.mjs:
 
 <br/>
 
+<a id="configuration"></a>
+## ⚙️ Configuration Reference (`.agent/config.yml`)
+
+`jules-orchestrator-kit` auto-detects stack defaults, but allows explicit overrides through `.agent/config.yml`:
+
+```yaml
+# .agent/config.yml — Universal Orchestrator Configuration
+
+version: 1
+provider: "jules"        # Provider key ("jules" | "claude-code" | "local")
+baseBranch: "main"       # Default target base branch
+branchPrefix: "agent/"   # Prefix for task branches
+
+# Verification commands (auto-detected by Stack Oracle if omitted)
+verify:
+  test: "npm test"
+  build: "npm run build"
+
+# Scope protection rules (Deny-first evaluation)
+scope:
+  deny:
+    - ".github/**"
+    - ".agent/config.yml"
+    - "keys/**"
+
+# Operational limits & governors
+limits:
+  diffKb: 75             # 75 KB Diff Payload Governor limit
+  promptKb: 50           # Maximum prompt payload size
+  dailyTasks: 300        # Daily task session quota limit
+  repairAttempts: 3      # Maximum OODA repair iterations
+  concurrency: 1         # Worker slot concurrency limit
+```
+
+<br/>
+
+---
+
+<br/>
+
 <a id="architecture"></a>
 ## 🏛️ System Architecture & Visual Diagrams
 
@@ -264,36 +322,14 @@ Every task dispatched to `jules-orchestrator-kit` executes within an immutable,
 
 <br/>
 
-```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
-```
-
-<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
-```
+<br/>
+
+<p align="center">
+  <img src="docs/assets/monorepo-resolver.svg" alt="Polyglot Monorepo Scoped Boundary Resolver" width="100%" />
+</p>
 
 <br/>
 
@@ -334,19 +370,59 @@ Native stdio server exposing task dispatch, gate verification, and risk auditing
 | :--- | :--- | :--- | :--- |
 | `init` | `agentctl init [--interactive] [--tier pro]` | Interactive onboarding wizard & stack oracle inspector generating `.agent/config.yml`. | `0` (Created) |
 | `task create` | `agentctl task create [--title <t>] [--prompt <p>]` | Interactively authors & scopes falsifiable task envelopes with secret scrubbing & preflight gate checks. | `0` (Queued), `1` (Unfalsifiable / Secret leak) |
+| `task optimize` | `agentctl task optimize "<prompt>" [--fix] [--json]` | Linter & optimizer scoring prompt falsifiability (0–100), fixing typos, and checking scope violations. | `0` (Scored/Fixed) |
+| `test-gen` | `agentctl test-gen --title <t> --spec <s> [--run]` | Scaffolds falsifiable unit tests, verifies **RED** failure state, and locks test in `scope.deny`. | `0` (Scaffolded/Red) |
+| `rollback` | `agentctl rollback [sessionId \| --latest]` | Restores exact commit, uncommitted files, and cleans orphan task worktrees from pre-flight checkpoints. | `0` (Restored), `1` (Error) |
+| `resume` | `agentctl resume <sessionId> --response "<reply>"` | Streams engineer response back into active Google Jules warm session context window. | `0` (Resumed), `1` (Error) |
 | `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) |
+| `doctor` | `agentctl doctor [--interactive] [--fix safe]` | Diagnostic DAG check runner & automated transactional repair planner. | `0` (Healthy) |
+| `queue` | `agentctl queue [--interactive] [--json]` | Consumes, inspects, and executes task envelopes in `.agent/jules-queue/` (supports `--json`). | `0` (Complete) |
+| `swarm` | `agentctl swarm [--interactive] [--json]` | Runs parallel multi-agent swarm across worker slots with process PID liveness detection (supports `--json`). | `0` (Complete) |
 | `scan` | `agentctl scan` | Scans codebase for TODO/FIXME annotations to seed task authoring. | `0` (Scanned) |
 | `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 --mode working-tree --json` | Runs security, secret scanning, and verification gate against working tree or branch. | `0` (Approved), `3` (Scope violation), `5` (Diff limit), `6` (Secret leak) |
+| `gate` / `audit`| `agentctl gate --mode working-tree [--json]` | Runs security, secret scanning, and verification gate against working tree or branch (supports `--json`). | `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) |
-| `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) |
 | `lock` | `agentctl lock <acquire\|release\|status>`| Manages VFS mutex locks for multi-agent non-overlapping file ownership. | `0` (Locked/Released), `1` (Conflict) |
 | `clean` | `agentctl clean` | Prunes stale git worktrees, lockfiles, and temporary ledgers. | `0` (Clean) |
 | `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.29.0`). | `0` |
+| `mcp init` | `agentctl mcp init [--target cursor\|vscode\|claude\|all]` | 1-click scaffolding for Cursor (`.cursor/mcp.json`), VS Code tasks (`tasks.json`), and Claude Desktop. | `0` (Scaffolded) |
+| `version` | `agentctl version` | Outputs orchestrator kit semantic version (`v0.30.0`). | `0` |
+
+<br/>
+
+---
+
+<br/>
+
+<a id="providers"></a>
+## 🔌 Provider Integration & SDK Usage
+
+`jules-orchestrator-kit` supports standard AI agent platforms and programmatic failover routing:
+
+### 1. Google Jules Native Integration
+Dispatch tasks using canonical task envelopes or the Google Jules REST v1alpha API.
+
+### 2. Multi-Provider Failover SDK (`createFailoverProvider`)
+Programmatically configure ordered provider failover (e.g. falling back to secondary providers on HTTP 429 rate limits):
+
+```javascript
+import { createFailoverProvider, loadConfig } from "jules-orchestrator-kit";
+
+const config = loadConfig(process.cwd());
+const provider = createFailoverProvider(["jules", "claude-code"], config);
+
+const result = await provider.dispatch(
+  { title: "Repair failing tests", prompt: "Fix the failing test suite." },
+  { root: process.cwd() }
+);
+```
+
+### 3. Model Context Protocol (MCP) Server
+Expose orchestrator gates and queue controls over stdio to client tools (Antigravity, Claude, Cursor):
+```bash
+npx jules-orchestrator-kit mcp
+```
 
 <br/>
 
@@ -355,15 +431,24 @@ Native stdio server exposing task dispatch, gate verification, and risk auditing
 <br/>
 
 <a id="roadmap"></a>
-## 🗺️ v0.29+ Feature Roadmap
+## 🗺️ Feature Roadmap & Release History
 
-| Feature | Module / Command | Architectural Blueprint | Target Release |
+| Feature | Module / Command | Architectural Description | Target Release |
 | :--- | :--- | :--- | :---: |
+| **Warm Session Resumption & PR Bundler** | `src/provider.mjs`, `src/engine.mjs` | Multi-turn warm session context streaming via `POST /v1alpha/sessions/{id}:sendMessage` & evidence PR descriptions. | **v0.31.0** *(Shipped)* |
+| **TDD Harness & Prompt Falsifiability Linter** | `agentctl test-gen`, `agentctl task optimize` | Automated RED-state test generator, `scope.deny` test locking, and prompt testability linter with fuzzy path resolution. | **v0.31.0** *(Shipped)* |
+| **Atomic Git Checkpoint & Rollback** | `agentctl rollback` (`src/ops/checkpoint.mjs`) | Pre-flight git HEAD/stash snapshotting, atomic rollback restoration, and 10-session pruning rotation. | **v0.31.0** *(Shipped)* |
+| **Verification Sandbox & SSR Hydration Prober** | `verify.server`, `verify.setup`/`teardown` | Isolated process group dev server probing, Next.js/React SSR panic detection, and deterministic DB hooks. | **v0.31.0** *(Shipped)* |
+| **AST Selective Testing & Escalation Bridge** | `src/dag-engine.mjs`, `agentctl escalate` | Downstream import test resolution, Slack/Discord webhook alerts, and async `agentctl resume` unblocking. | **v0.31.0** *(Shipped)* |
+| **IDE Native MCP Config Scaffolder** | `agentctl mcp init` (`src/ops/ide-scaffold.mjs`) | 1-click scaffolding for Cursor (`.cursor/mcp.json`), VS Code tasks (`tasks.json`), and Claude Desktop. | **v0.31.0** *(Shipped)* |
+| **Interactive UX Engine & TUI Engine** | `src/ux/` (`capabilities`, `key-decoder`, `renderer`, `layout`, `widgets`) | Zero-dependency terminal capabilities detector, sequence key decoder, virtual frame renderer, and widgets. | **v0.30.0** *(Shipped)* |
+| **Guided Diagnostics & Transactional Core** | `src/ops/` (`doctor-registry`, `doctor-planner`, `transaction`, `receipts`) | Diagnostic check DAG (`runDoctorChecks`), pure fix planner (`planDiagnosticFixes`), and transactional executor with rollback. | **v0.30.0** *(Shipped)* |
+| **Interactive Queue & Swarm Manager** | `src/ux/`, `src/ops/` (`queue-model`, `swarm-model`, `task-actions`, `swarm-actions`) | Task sidecar state machine, queue snapshot builder, PID liveness reconciler, task actions, and swarm actions. | **v0.30.0** *(Shipped)* |
+| **Command Registry & Command Palette** | `src/ops/command-registry.mjs`, `src/ux/palette.mjs` | Single-source command descriptor registry (`COMMAND_REGISTRY`), `--help` string formatter, fuzzy search filter, and command palette. | **v0.30.0** *(Shipped)* |
 | **Onboarding & Stack Oracle Wizard** | `agentctl init --interactive` (`src/wizard-init.mjs`) | Zero-dependency interactive CLI wizard auto-detecting verification oracles, quota tiers, and preset workflows. | **v0.29.0** *(Shipped)* |
 | **Guided Task Authoring Subsystem** | `agentctl task create` (`src/wizard-task.mjs`) | Guided task authoring with TODO candidate harvesting, Shannon entropy secret scrubbing, and guardrail footer synthesis. | **v0.29.0** *(Shipped)* |
-| **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)* |
+| **P0 Remediation & Safety Alignment** | Queue, Task Envelope & Secrets (`src/wizard-task.mjs`) | Canonical queue path alignment (`.agent/jules-queue/`), path traversal guards, atomic writes, multiline secret scans, and JSON headers. | **v0.29.1** *(Shipped)* |
+| **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. | **v0.27.0** *(Shipped)* |
 
 <br/>
 
@@ -371,12 +456,10 @@ Native stdio server exposing task dispatch, gate verification, and risk auditing
 
 <br/>
 
-## 📖 Recipes, Documentation & Prior Art
+## 📖 Documentation & Architecture
 
+- [**System Architecture & Pipeline Overview**](./docs/architecture.md) — Comprehensive technical sequence diagram and control plane architecture.
 - [**Google Jules Official Documentation**](https://jules.google) — Official platform overview and API specifications for Google Jules.
-- [**Onboarding & Task Wizard Specification**](./docs/ONBOARDING_AND_TASK_WIZARD_SPEC.md) — Normative architecture specification for zero-dependency TUI, stack oracle, and guided task authoring.
-- [**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.
 - [**Changelog**](./CHANGELOG.md) — Full release history and migration guides.
 

package/bin/agentctl.mjs

@@ -2,7 +2,7 @@
 
 import { parseArgs } from "node:util";
 import { readFileSync, existsSync, readdirSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { loadConfig, resolveRoot, detectStack, bootstrapZeroTestRepo } from "../src/config.mjs";
 import { gate, dispatch, run, isTaskFile } from "../src/engine.mjs";
 import { acquireLock, releaseLock, lockStatus, checkDailyBudget, getQueueDir } from "../src/state.mjs";
@@ -14,7 +14,7 @@ const command = args[0];
 
 function printHelp() {
   console.log(`
-🚀 agentctl v0.29.1 — Universal Agent Orchestrator & Safety Gatekeeper
+🚀 agentctl v0.30.0 — Universal Agent Orchestrator & Safety Gatekeeper
 
 Usage: agentctl <command> [options]
 
@@ -32,6 +32,11 @@ Commands:
   dashboard             Start local HTTP telemetry and audit dashboard
   init                  Scaffold .agent/ config and run onboarding wizard
   task create           Interactively author and scope a Jules task envelope
+  task optimize         Linter & optimizer for Jules task prompts (--fix, --json)
+  test-gen              Scaffold & run automated TDD Red-to-Green test cycle (--run)
+  mcp init              Scaffold IDE integration config (cursor | vscode | claude | all)
+  rollback              Restore git state & working tree to atomic pre-flight checkpoint
+  resume                Resume warm session with human response (--response "<text>")
   status                Display queue and system status summary
   scan                  Scan codebase for TODO/FIXME task candidates
   version               Output agentctl version
@@ -391,8 +396,66 @@ async function main() {
           console.log(`   Auto-PR  : ${res.plan.flags.autoPr}`);
         }
         process.exit(0);
+      } else if (subCommand === "optimize") {
+        const { values, positionals } = parseArgs({
+          args: args.slice(2),
+          options: {
+            fix: { type: "boolean", short: "f" },
+            file: { type: "string" },
+            dir: { type: "string", short: "d" },
+            json: { type: "boolean", short: "j" },
+            "verify-cmd": { type: "string", short: "v" },
+          },
+          allowPositionals: true,
+        });
+
+        const { scorePromptFalsifiability, optimizeTaskPrompt } = await import("../src/task-optimizer.mjs");
+        const targetDir = values.dir ? resolve(values.dir) : root;
+        let promptText = positionals.join(" ");
+
+        if (values.file) {
+          if (existsSync(values.file)) {
+            promptText = readFileSync(values.file, "utf-8");
+          } else {
+            console.error(`Error: File '${values.file}' does not exist.`);
+            process.exit(1);
+          }
+        }
+
+        if (values.fix) {
+          const opt = optimizeTaskPrompt(promptText, { rootDir: targetDir, verifyCmd: values["verify-cmd"] });
+          if (values.json) {
+            console.log(JSON.stringify(opt, null, 2));
+          } else {
+            console.log(opt.optimizedPrompt);
+          }
+          process.exit(0);
+        }
+
+        const analysis = scorePromptFalsifiability(promptText, { rootDir: targetDir, verifyCmd: values["verify-cmd"] });
+        if (values.json) {
+          console.log(JSON.stringify(analysis, null, 2));
+        } else {
+          console.log(`\n🎯 Task Prompt Falsifiability Analysis`);
+          console.log(`--------------------------------------------------`);
+          console.log(`  Score / Grade    : ${analysis.score} / 100 (${analysis.grade})`);
+          console.log(`  Falsifiable      : ${analysis.isFalsifiable ? "✅ YES" : "❌ NO"}`);
+          if (analysis.oracle.command) {
+            console.log(`  Oracle Command   : "${analysis.oracle.command}" (${analysis.oracle.autoDetected ? "Auto-detected" : "User-supplied"})`);
+          }
+          if (analysis.issues.length > 0) {
+            console.log(`\n  Issues Identified (${analysis.issues.length}):`);
+            analysis.issues.forEach((i) => console.log(`   - [${i.type}] ${i.message} (-${i.penalty} pts)`));
+          }
+          if (analysis.suggestions.length > 0) {
+            console.log(`\n  Suggestions for Improvement:`);
+            analysis.suggestions.forEach((s) => console.log(`   - ${s}`));
+          }
+          console.log(`--------------------------------------------------\n`);
+        }
+        process.exit(analysis.isFalsifiable ? 0 : 1);
       } else {
-        console.error(`Unknown task subcommand '${subCommand}'. Supported: agentctl task create`);
+        console.error(`Unknown task subcommand '${subCommand}'. Supported: agentctl task create, agentctl task optimize`);
         process.exit(1);
       }
       break;
@@ -427,7 +490,143 @@ async function main() {
       break;
     }
 
+    case "rollback": {
+      const { restoreCheckpoint } = await import("../src/ops/checkpoint.mjs");
+      const targetId = args[1] || "--latest";
+      try {
+        const res = restoreCheckpoint(targetId, { root });
+        console.log(`\n✅ Git Checkpoint Restored Successfully!`);
+        console.log(`   Session ID : ${res.id}`);
+        console.log(`   HEAD SHA   : ${res.headSha || "N/A"}`);
+        console.log(`   RestoredAt : ${res.restoredAt}\n`);
+        process.exit(0);
+      } catch (err) {
+        console.error(`❌ Rollback Failed: ${err.message}`);
+        process.exit(1);
+      }
+      break;
+    }
+
+    case "resume": {
+      const { createProvider } = await import("../src/provider.mjs");
+      const sessionId = args[1];
+      const { values } = parseArgs({
+        args: args.slice(1),
+        options: {
+          response: { type: "string", short: "r" },
+          "dry-run": { type: "boolean", short: "d" },
+          json: { type: "boolean", short: "j" },
+        },
+        allowPositionals: true,
+      });
+
+      if (!sessionId || sessionId.startsWith("-")) {
+        console.error("Error: Session ID is required for agentctl resume <sessionId>.");
+        process.exit(1);
+      }
+
+      const responseText = values.response || args.slice(2).join(" ");
+      if (!responseText) {
+        console.error("Error: --response text is required to resume warm session.");
+        process.exit(1);
+      }
+
+      const provider = createProvider(config.provider || "jules", config);
+      try {
+        const res = await provider.resume(sessionId, responseText, { root, dryRun: values["dry-run"] });
+        if (values.json) {
+          console.log(JSON.stringify(res, null, 2));
+        } else {
+          console.log(`\n✅ Warm Session Resumed Successfully!`);
+          console.log(`   Session ID : ${res.id}`);
+          console.log(`   Status     : ${res.status}\n`);
+        }
+        process.exit(0);
+      } catch (err) {
+        console.error(`❌ Resume Failed: ${err.message}`);
+        process.exit(1);
+      }
+      break;
+    }
+
+    case "test-gen": {
+      const { scaffoldTddTest, runTddCycle } = await import("../src/ops/tdd-generator.mjs");
+      const { values } = parseArgs({
+        args: args.slice(1),
+        options: {
+          title: { type: "string", short: "t" },
+          spec: { type: "string", short: "s" },
+          run: { type: "boolean", short: "r" },
+          json: { type: "boolean", short: "j" },
+        },
+        allowPositionals: true,
+      });
+
+      const title = values.title || args[1] || "feature-spec";
+      const specText = values.spec || args.slice(2).join(" ") || "TDD requirement specification.";
+
+      try {
+        if (values.run) {
+          const res = await runTddCycle({ title, spec: specText }, { root });
+          if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+          } else {
+            console.log(`\n🔴 TDD RED Check Verified!`);
+            console.log(`   Test File   : ${res.testFile}`);
+            console.log(`   Scope Lock  : Locked into scope.deny`);
+            console.log(`   Status      : Ready for green implementation dispatch\n`);
+          }
+        } else {
+          const scaffold = scaffoldTddTest({ title, spec: specText }, { root });
+          if (values.json) {
+            console.log(JSON.stringify(scaffold, null, 2));
+          } else {
+            console.log(`\n🧪 TDD Test Scaffolded Successfully!`);
+            console.log(`   File Path : ${scaffold.relativePath}`);
+            console.log(`   Command   : ${scaffold.testCmd}\n`);
+          }
+        }
+        process.exit(0);
+      } catch (err) {
+        console.error(`❌ TDD Generation Failed: ${err.message}`);
+        process.exit(1);
+      }
+      break;
+    }
+
     case "mcp": {
+      const subAction = args[1];
+      if (subAction === "init") {
+        const { scaffoldIdeConfig } = await import("../src/ops/ide-scaffold.mjs");
+        const { values } = parseArgs({
+          args: args.slice(2),
+          options: {
+            target: { type: "string", short: "t", default: "all" },
+            json: { type: "boolean", short: "j" },
+          },
+          allowPositionals: true,
+        });
+
+        const target = values.target || args[2] || "all";
+        try {
+          const res = scaffoldIdeConfig(target, { root });
+          if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+          } else {
+            console.log(`\n🔌 IDE MCP Config Scaffolded Successfully!`);
+            console.log(`   Target  : ${res.target}`);
+            for (const item of res.results) {
+              console.log(`   - ${item.target.toUpperCase()} : ${item.file}`);
+            }
+            console.log("");
+          }
+          process.exit(0);
+        } catch (err) {
+          console.error(`❌ IDE MCP Scaffold Failed: ${err.message}`);
+          process.exit(1);
+        }
+      }
+
       const { startMcpServer } = await import("../src/mcp.mjs");
       startMcpServer();
       break;

package/index.mjs

@@ -85,4 +85,24 @@ export { planInit, loadPresets, runInitWizard, TIER_PROFILES, BUILTIN_PRESETS }
 // Guided Task Authoring Subsystem
 export { planTaskCreate, runTaskCreateWizard, GUARDRAIL_FOOTER } from "./src/wizard-task.mjs";
 
+// Prompt Falsifiability & Task Optimizer Engine
+export { scorePromptFalsifiability, optimizeTaskPrompt, levenshteinDistance, extractPathTokens } from "./src/task-optimizer.mjs";
+
+// Atomic Git Checkpoints & Rollback
+export { createCheckpoint, restoreCheckpoint, listCheckpoints, pruneCheckpoints, CheckpointError } from "./src/ops/checkpoint.mjs";
+
+// Webhook & HITL Escalation Bridge
+export { dispatchEscalation, verifySignature, parseWebhookPayload, routeWebhookEvent, createWebhookServer } from "./src/webhook.mjs";
+
+// PR Review Evidence Bundler & Dev Server Probe
+export { synthesizePrDescription, probeDevServer } from "./src/engine.mjs";
+
+// Automated TDD Red-to-Green Harness
+export { scaffoldTddTest, runTddCycle, TddError } from "./src/ops/tdd-generator.mjs";
+
+// IDE Native MCP Scaffolder
+export { scaffoldIdeConfig, IdeScaffoldError } from "./src/ops/ide-scaffold.mjs";
+
+
+