jules-orchestrator-kit 0.39.0 → 0.41.1

package/.agent/prompts/Bolt.md

@@ -1,18 +1,21 @@
 # Bolt - Performance & Payload Optimization Specialist ⚡
 
 > **Role:** Codebase Micro-Optimizer & Payload Governor.
-> **Scope:** Performance tuning, bundle size reduction, and asset optimization with zero structural side-effects.
+> **Scope:** Performance tuning, artifact size reduction, and asset optimization with zero structural side-effects.
 
 ## Core Directives
 
 1. **Payload Budgeting:**
-   - Keep total diff payload strictly under 75 KB (`git diff | wc -c`).
-   - Eliminate redundant dependencies by replacing 3rd-party modules with Node.js built-ins (`node:fs`, `node:path`, `node:crypto`).
+   - Keep total diff payload strictly under {{DIFF_KB}} KB (`git diff | wc -c`).
+   - Prefer this project's existing dependencies and its language's standard library over adding another third-party module. Removing a dependency whose job the standard library already does is in scope; adding one is not.
 
 2. **Asset & Memory Optimization:**
-   - Replace heavy raster assets with modern WebP/AVIF equivalents or clean SVGs.
-   - Optimize hot execution paths: remove redundant object allocations inside tight loops.
+   - Replace heavy raster assets with modern equivalents (WebP/AVIF) or clean vector graphics, where the project already serves such formats.
+   - Optimize hot execution paths: remove redundant allocations inside tight loops, and hoist work out of repeated calls.
 
-3. **Zero Regressions Invariant:**
-   - Execute test suite (`npm test`) before and after every micro-optimization pass.
+3. **Evidence Before Claims:**
+   - A performance change requires numbers. Run the benchmark or timing measurement multiple times, compare medians, and state the delta. "Feels faster" is not a result, and a change below the noise floor is not an improvement.
+
+4. **Zero Regressions Invariant:**
+   - Execute `{{VERIFY_TEST}}` before and after every optimization pass, and record both results.
    - Never disable type-checks, skip tests, or alter public API signatures.

package/.agent/prompts/Janitor.md

@@ -1,11 +1,11 @@
 # Janitor Protocol: Technical Debt & Dead Code Elimination
 
-You are **Janitor**, a specialist autonomous agent optimized for technical debt elimination, dead code pruning, and strict zero-dependency refactoring.
+You are **Janitor**, a specialist autonomous agent optimized for technical debt elimination, dead code pruning, and conservative refactoring.
 
 ## Strict Operational Invariants
 
-1. **Zero External Runtime Dependencies**: You are STRICTLY FORBIDDEN from adding third-party npm packages. Use ONLY native Node.js ESM built-in modules (`node:fs`, `node:path`, `node:crypto`, `node:child_process`, `node:os`).
-2. **Dead Code Elimination**: Prune unused variables, unreachable branches, and redundant helper functions.
-3. **Atomic Payload Limit**: Keep total patch payload under 75 KB (`git diff | wc -c`).
-4. **Verification Requirement**: Execute `npm test` and `npm run lint` to ensure 100% of tests pass with 0 lint errors before completing work.
-5. **No Assert Weakening**: Never weak or remove test assertions to make a test pass.
+1. **No New Dependencies**: Do NOT add third-party packages, libraries, or modules of any kind. Solve the task with this project's existing dependencies and its language's standard library. If a task genuinely cannot be completed without a new dependency, stop and say so instead of adding one.
+2. **Dead Code Elimination**: Prune unused variables, unreachable branches, and redundant helper functions. Confirm a symbol has no remaining references across the whole repository before removing it — including dynamic lookups, reflection, and string-keyed access, which a definition-search will not find.
+3. **Atomic Payload Limit**: Keep total patch payload under {{DIFF_KB}} KB (`git diff | wc -c`).
+4. **Verification Requirement**: Execute `{{VERIFY_TEST}}` and `{{VERIFY_LINT}}` and ensure 100% of tests pass with 0 lint errors before completing work.
+5. **No Assert Weakening**: Never weaken or remove test assertions to make a test pass. Leave an unmet requirement RED with a written rationale.

package/.agent/prompts/Task_Template.md

@@ -8,18 +8,19 @@
 ## Context
 - **Project Goals:** [Describe key architectural or business goals.]
 - **Key Files & Folders:** [List critical files, directories, or schemas, e.g. `src/auth.ts`, `schema.sql`.]
-- **Tech Stack:** [List frameworks and libraries, e.g. Node.js, Express, TypeScript, Drizzle ORM.]
+- **Tech Stack:** [List this project's languages, frameworks, and libraries.]
 
 ## Requirements & Hard Constraints
 - **Functional Requirements:** [List specific, non-negotiable functional requirements.]
 - **Hard Constraints:**
-  - Do NOT introduce third-party npm dependencies without explicit authorization.
-  - Do NOT modify command files (`package.json`, `.github/`) or Agent Scope files.
-  - Keep total diff payload strictly under 75 KB (`git diff | wc -c`).
+  - Do NOT introduce new third-party dependencies without explicit authorization.
+  - Do NOT modify this project's build manifest, lockfile, CI configuration, or agent scope files. Run `agentctl gate` to see the enforced set.
+  - Keep total diff payload strictly under {{DIFF_KB}} KB (`git diff | wc -c`).
 
 ## Verification Loop
-- **Verification Command:** Execute automated verification tests: `npm test`.
+- **Verification Command:** Execute `{{VERIFY_TEST}}`.
 - **Zero Errors Invariant:** Ensure 100% of tests pass cleanly with 0 errors before submitting.
+- **Carry the Evidence:** Paste the actual terminal output. Exit code 0 proves the process survived, not that the change works.
 
 ## Expected Artifacts
 - **Code Changes:** Clean, production-grade implementation preserving existing symbol contracts.

package/JULES_RULES_TEMPLATE.md

@@ -80,8 +80,8 @@ Jules automatically infers test and build verification commands via `scripts/com
 
 ## 6. Local CI Verification with Nektos Act
 
-- **Pre-Push CI Validation**: When `.github/workflows/` exists and Nektos `act` is installed, execute `act push` or `bash scripts/act/run-act.sh` to verify changes pass CI locally inside the VM before opening a PR.
-- **Log Inspection**: If local `act` CI fails, inspect `act_output.log`, resolve errors in code, and re-run verification before pushing.
+- **Pre-Push CI Validation**: When `.github/workflows/` exists and Nektos `act` is installed, execute `act push` to verify changes pass CI locally inside the VM before opening a PR. Skip this step if `act` is not on `PATH` — do not install it and do not invent a wrapper script for it.
+- **Log Inspection**: If local `act` CI fails, inspect its output, resolve errors in code, and re-run verification before pushing.
 - **Diff Payload Governor**: API forcefully truncates diff payloads > 80 KB. Keep total diff payload under 75 KB (`git diff | wc -c`).
 
 ---
@@ -101,7 +101,11 @@ To maximize the ratio of mergeable PRs vs. failed or hallucinated sessions, adhe
 
 ### Standard Jules Guardrails Footer
 
-Append this footer to all Jules dispatches:
+`agentctl task create` appends this automatically, generated from your own
+`.agent/config.yml` scope — so the protected-path line lists *your* build
+manifests (`Cargo.toml`, `go.mod`, `pyproject.toml`, `composer.json`, …) and
+rebases onto *your* base branch. Fill the placeholders only for hand-written
+dispatches; run `agentctl gate` to see the full enforced set.
 
 ```text
 Read AGENTS.md and .agent/rules/jules-protocol.md BEFORE starting.
@@ -110,12 +114,12 @@ Follow all rules strictly.
 TASK: <description>
 
 HARD CONSTRAINTS:
-- Do NOT modify package.json, pnpm-lock.yaml, tsconfig.json, or .github/ files. Enforced in CI by Agent Scope Guard.
+- Do NOT modify these protected paths: <your build manifest, lockfile, CI directory, and agent rules>.
 - Diff Payload Governor: Keep total diff payload under 75 KB (`git diff | wc -c`) to prevent API truncation (~80 KB limit).
 - Falsifiable & Evidence-Based: Attach full terminal verification output to PR. Never weaken assertions or delete failing tests to force a pass.
 - Declare Scope Deviations: If modifying files outside task bounds, explicitly state rationale in PR.
-- Verify before finishing: Run full type-check, lint, and unit test suites.
-- BEFORE opening the PR: Run `git fetch origin main && git rebase origin/main`, then re-verify. If the rebase leaves an empty diff, the work already landed — do NOT submit.
-- Delete ALL temporary files (.py, .sh, .patch, debug logs) before submitting.
+- Verify before finishing: Run the project's full type-check, lint, and test commands.
+- BEFORE opening the PR: Run `git fetch origin <base> && git rebase origin/<base>`, then re-verify. If the rebase leaves an empty diff, the work already landed — do NOT submit.
+- Remove any scratch files you created for debugging before submitting. Do not delete files that are part of the project.
 ```
 

package/README.md

@@ -51,16 +51,28 @@
 Get running in any repository in 3 commands (zero configuration required):
 
 ```bash
-# 1. Initialize orchestrator in your project (auto-detects Python, Rust, Go, Node, PHP, etc.)
+# 1. Scaffold config, AGENTS.md, role prompts and guardrails
+#    (auto-detects Python, Rust, Go, Node, PHP, etc.)
 npx jules-orchestrator-kit init
+```
 
-# 2. Author a scoped, verified task envelope with guardrails & secret scrubbing
-npx jules-orchestrator-kit task create
+```bash
+# 2. Commit what init wrote — .agent/config.yml is on the gate's deny list by
+#    design, so leaving it uncommitted makes the first gate reject your tree
+git add .agent AGENTS.md .gitignore && git commit -m "chore: add agent config"
+```
 
-# 3. Inspect repository health & diagnostic status
-npx jules-orchestrator-kit doctor
+```bash
+# 3. Author a scoped, verified task envelope with guardrails & secret scrubbing
+npx jules-orchestrator-kit task create
 ```
 
+> [!TIP]
+> **Not sure what to run next?**  
+> `agentctl` with no arguments reads the repository state and prints the single
+> next step — missing git repo, missing API key, empty queue, tasks ready to
+> dispatch — instead of a wall of commands.
+
 > [!TIP]
 > **Prefer a global CLI?**  
 > Install globally to access `agentctl` directly:
@@ -129,9 +141,9 @@ To maximize PR merge rates, dispatch tasks according to deterministic boundaries
 * **Cross-Platform Parity:** Verified 100% green across Linux, macOS (Darwin), and Windows on Node 20, 22, and 24.
 * **Autonomous Self-Healing Loop:** Captures test stderr/stdout, fingerprints error traces, and feeds structured context back into automated repair turns (up to 3 attempts) before human escalation.
 * **Fail-Closed Security & Secret Redaction:** Evaluates explicit Deny rules before Allow rules against canonicalized, case-folded paths. Redacts high-entropy keys and base64-encoded credentials (such as Kubernetes `Secret` manifests).
-* **Complexity & Cost Router:** Zero-dependency heuristic classifier (`src/router.mjs`) routing mechanical tasks to lightweight models while reserving primary models for complex refactors.
+* **Complexity & Cost Router:** Zero-dependency heuristic classifier (`src/router.mjs`) routing mechanical tasks to lightweight models while reserving primary models for complex refactors, with a `node --check` syntax-verification gate that transparently escalates a FAST-tier result to the primary provider if it left broken JS on disk.
 * **Terminal UI & Diagnostic Matrix (`agentctl doctor`):** Interactive terminal dashboard, task sidecar manager, and automated transactional self-repair.
-* **Verified Test Suite:** Tested with **602 unit tests across 83 suites passing in < 10.0s**.
+* **Verified Test Suite:** Tested with **706 unit tests across 85 suites passing in < 10.0s**.
 
 <br/>
 
@@ -146,17 +158,18 @@ To maximize PR merge rates, dispatch tasks according to deterministic boundaries
 
 | Command | Usage | Description | Exit Codes |
 | :--- | :--- | :--- | :--- |
-| `init` | `agentctl init [--interactive] [--tier pro]` | Interactive onboarding wizard & stack detector generating `.agent/config.yml`. | `0` (Created) |
-| `task create` | `agentctl task create [--title <t>] [--prompt <p>] [--template <id>] [--role <name>] [--tier fast\|complex]` | Interactively authors & scopes falsifiable task envelopes with secret scrubbing, preflight gate checks, and DAG dependency wiring. | `0` (Queued), `1` (Secret/Unfalsifiable) |
-| `task template` | `agentctl task template [<id>] [--list] [--json]` | Lists and synthesizes pre-calibrated task envelopes (Web & Agent Hardening: `web-cwv`, `web-wcag`, `web-seo`, `web-playwright`, `agent-dead-code-audit`, `web-flaky-heal`, `web-i18n`, `web-ai-access`, `agent-qa-mutation`, `agent-ci-falsify`, `agent-service-isolate`, `agent-error-paths`, `agent-security-audit`). | `0` (Listed/Synthesized) |
-| `dispatch` | `agentctl dispatch [-p <prompt>] [-f <file>] [-r <role>] [-t <tier>] [--check-premise] [--auto-pr] [--repoless] [--dry-run]` | Dispatches autonomous task to the active provider with pre-flight idempotency checks, payload limits, and role prompt resolution. | `0` (Dispatched), `1` (Error) |
+| `init` | `agentctl init [--interactive] [--tier pro] [--force]` | Interactive onboarding wizard & stack detector. Generates `.agent/config.yml` and scaffolds `AGENTS.md`, the role prompts, the guardrails and the runtime `.gitignore` entries. Existing files are preserved unless `--force`. | `0` (Created) |
+| `budget` | `agentctl budget [--by-user] [--json] [reset]` | Reports rolling 24h task budget, quota headroom, and per-developer task attribution without external auth servers. | `0` (Status), `2` (Arg Error) |
+| `task create` | `agentctl task create [<prompt>] [--title <t>] [-p <prompt>] [-f <file>] [--template <id>] [--role <name>] [--tier fast\|complex]` | Interactively authors & scopes falsifiable task envelopes with secret scrubbing, preflight gate checks, and DAG dependency wiring. | `0` (Queued), `1` (Secret/Unfalsifiable) |
+| `task template` | `agentctl task template [<id>] [--list] [--json]` | Lists and synthesizes pre-calibrated task envelopes (Web, Deep Think & Agent Hardening: `web-cwv`, `web-wcag`, `web-seo`, `web-playwright`, `agent-dead-code-audit`, `web-flaky-heal`, `web-i18n`, `web-ai-access`, `agent-qa-mutation`, `agent-ci-falsify`, `agent-service-isolate`, `agent-error-paths`, `agent-security-audit`, `deep-debug`, `deep-feature`, `deep-optimize`, `deep-harden`). | `0` (Listed/Synthesized) |
+| `dispatch` | `agentctl dispatch [<prompt>] [-p <prompt>] [-f <file>] [-r <role>] [-t <tier>] [--author <name>] [--check-premise] [--auto-pr] [--repoless] [--dry-run]` | Dispatches autonomous task to the active provider with pre-flight idempotency checks, payload limits, and role prompt resolution. `--dry-run` stops short of the provider call and reports itself as a rehearsal rather than a dispatch. | `0` (Dispatched), `1` (Error) |
 | `plan approve` | `agentctl plan approve <sessionId> [--dry-run] [--json]` | Approves pending execution plan for an active Jules session (`:approvePlan`) with automatic 404/503 retry backoff. | `0` (Approved), `1` (Error) |
 | `session get` | `agentctl session get <sessionId> [--dry-run] [--json]` | Retrieves live session lifecycle state from provider REST API with token rotation. | `0` (Fetched), `1` (Error) |
-| `pr harvest` | `agentctl pr harvest [--tier r0,r1] [--limit <n>] [--auto] [--dry-run]` | Discovers open agent PRs, evaluates CI checks & risk tiers, and auto-squashes green low-risk changes autonomously. | `0` (Triaged/Merged), `1` (Error) |
+| `pr harvest` | `agentctl pr harvest [--tier r0,r1] [--limit <n>] [--auto] [--allow-no-checks] [--dry-run]` | Discovers open agent PRs, evaluates CI checks & risk tiers, and auto-squashes green low-risk changes autonomously. A PR reporting **no** CI checks is skipped unless `--allow-no-checks` is passed, and an unavailable changed-file list blocks rather than classifying as low risk. | `0` (Triaged/Merged), `1` (Error) |
 | `doctor` | `agentctl doctor [--json]` | Diagnostic DAG check runner & automated transactional self-repair engine. | `0` (Healthy), `1` (Failures) |
 | `queue` | `agentctl queue [--dag] [--concurrency <n>] [--dry-run] [--json]` | Consumes and executes task envelopes in `.agent/jules-queue/` with Kahn's DAG dependency resolution. Non-task files (manifests, `README.md`) are skipped, and `--dry-run` previews without moving anything. | `0` (Complete) |
 | `swarm` | `agentctl swarm [--json]` | Runs parallel multi-agent swarm across worker slots with PID liveness detection. | `0` (Complete) |
-| `gate` / `audit`| `agentctl gate --mode working-tree [--json] [--json-report <path>]` | Runs security, secret scanning, and tiered verification gates (with declarative assertion support) against working tree or branch. | `0` (Approved), `3` (Scope), `5` (Diff >75K), `6` (Secret) |
+| `gate` / `audit`| `agentctl gate --mode working-tree [--fix] [--json] [--json-report <path>]` | Runs security, secret scanning, and tiered verification gates (with declarative assertion support) against working tree or branch. Secret findings name the file and line; a failed verify stage reports its command, exit code and output. | `0` (Approved), `3` (Scope), `4` (Verify), `5` (Diff >75K), `6` (Secret), `8` (Flaky) |
 | `assert` | `agentctl assert [--dir <d>] [--file <f>] [--max-mb <n>] [--gzip] [--targets <g>] [--patterns <p>] [--json] [--json-report <p>]` | Runs declarative zero-dependency verification assertion primitives (`assert:dir-size`, `assert:file-size`, `assert:file-patterns`, `assert:exists`). | `0` (Passed), `1` (Assertion Failed) |
 | `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) |
@@ -203,13 +216,28 @@ scope:
     - ".agent/config.yml"
     - "keys/**"
 
-# Operational limits & governors
+# Plan tier. Defaults to `free` when unset — the kit will not assume you are
+# paying for a larger plan than you are. Set this to unlock your real limits.
+tier: "free"             # free | pro | ultra
+
+# Risk model for auto-merge triage. Builtin patterns cover what is dangerous in
+# any repository (CI, lockfiles, migrations, key material, IaC, auth). Add the
+# paths that are sensitive to YOUR domain — these EXTEND the builtins.
+risk:
+  restricted:            # R3 — never auto-merged
+    - "**/pricing/**"
+    - "**/billing/**"
+  consequential:         # R2 — always requires a human read
+    - "packages/api/**"
+  max_routine_diff_lines: 400
+
+# Operational limits & governors (tier defaults shown; any key here overrides)
 limits:
-  diffKb: 75             # 75 KB Diff Payload Governor limit
+  diffKb: 75             # Diff Payload Governor limit
   promptKb: 50           # Maximum prompt payload size
   dailyTasks: 300        # Task quota per rolling 24h window (not per calendar day)
   repairAttempts: 3      # Maximum repair iterations
-  concurrency: 15        # Worker slots (free: 3, pro: 8, ultra: 15)
+  concurrency: 15        # Worker slots (defaults free: 3, pro: 8, ultra: 15)
 
 # Dynamic Complexity & Cost Router — opt-in, disabled by default.
 router:
@@ -312,6 +340,23 @@ const { provider, classification } = resolveRoutedProvider(
 console.log(classification.tier); // "fast" | "complex"
 ```
 
+### Syntax-Verified FAST Tier (`createSyntaxVerifiedProvider`)
+`resolveRoutedProvider()` already wraps the FAST tier with this; use it directly only when composing your own provider cascade.
+```javascript
+import { createProvider, createSyntaxVerifiedProvider, loadConfig } from "jules-orchestrator-kit";
+
+const config = loadConfig(process.cwd());
+const fast = createSyntaxVerifiedProvider(
+  createProvider("gemini-flash", config),
+  createProvider("jules", config),
+  config
+);
+
+// If gemini-flash leaves broken .js/.mjs/.cjs on disk, this transparently
+// re-dispatches through "jules" instead of returning the broken result.
+const result = await fast.dispatch({ prompt: "Fix a typo." }, { root: process.cwd() });
+```
+
 </details>
 
 <br/>
@@ -323,6 +368,8 @@ console.log(classification.tier); // "fast" | "complex"
 
 | Feature | Module / Command | Architectural Description | Status |
 | :--- | :--- | :--- | :---: |
+| **Diagnostics That Reach the Operator** | `src/security.mjs`, `src/engine.mjs`, `bin/agentctl.mjs` | Secret findings name the file and line, a failed verify stage reports its command, exit code and output, and `queue`/`swarm` name each failed task and exit `1` rather than reporting success for a run that dispatched nothing. | **v0.41.1** *(Shipped)* |
+| **One Scaffolding Path & First-Install Fixes** | `src/scaffold.mjs`, `src/security.mjs` | `agentctl init` and `jules-init` scaffold from one source and write the runtime `.gitignore` entries, so the kit's own bookkeeping no longer reaches its own gate; a lockfile bump no longer fails closed as a secret leak. | **v0.41.1** *(Shipped)* |
 | **Queue Runner Fidelity** | `src/dag-engine.mjs`, `src/engine.mjs` | Queue selection is by task shape rather than file extension, so manifests and READMEs are skipped instead of dispatched, and `--dry-run` leaves the queue untouched. | **v0.38.2** *(Shipped)* |
 | **Release Gate Enforcement & Wizard Smoke Test** | `.github/workflows/jules-audit.yml`, `scripts/release.mjs`, `test/wizard-smoke.test.mjs` | Doc-sync gate runs in CI rather than by hand, releases block on a green CI matrix for `HEAD`, per-test deadlines turn a hang into a failure, and the real `init` wizard is driven end to end over a fake TTY. | **v0.38.1** *(Shipped)* |
 | **Multi-OS CI Matrix & TUI Hardening** | `scripts/run-tests.mjs`, `src/state.mjs`, `src/git.mjs` | Automated 9-job CI matrix across Linux, macOS, and Windows on Node 20/22/24 with raw-mode TUI resilience and native Windows command quoting. | **v0.38.0** *(Shipped)* |