jules-orchestrator-kit 0.38.1 → 0.39.0

package/.agent/rules/jules-protocol.md

@@ -32,7 +32,7 @@ To maximize the ratio of mergeable PRs vs. failed or hallucinated sessions:
 11. **Pre-Dispatch Grounding Mandate:** Verify all file paths, script names, and exported symbols against the live repository tree before writing them into a prompt.
 12. **Programmatic CI Scope Guarding:** Enforce prompt constraints at the CI level using an unbypassable `Agent Scope Guard` workflow that evaluates diffs against a protected paths manifest (`.agent/protected-paths.json`).
 13. **Google Labs Exploration Budget Protocol:** Execute tasks across 3 discrete phases: (1) Discovery & Symbol Tracing (silent inspection, write NO code), (2) Oracle & Test Formulation, and (3) Surgical Implementation & Verification.
-14. **Critic Agent Steering (Adversarial Pre-Review):** Jules' internal Critic Agent must evaluate proposed patches for edge-case regressions, $O(n^2)$ bottlenecks, unhandled parameters, and layout shifts (CLS) prior to PR submission.
+14. **Critic Agent Steering (Adversarial Pre-Review):** Jules' internal Critic Agent must evaluate proposed patches for edge-case regressions, $O(n^2)$ bottlenecks, unhandled parameters, and layout shifts (CLS) prior to PR submission. When modifying test suites or error handling, the agent must deliberately mutate production code and induce real failure conditions to prove that tests and catch blocks actually fail as intended (preventing tautological tests).
 15. **Web Excellence & Frontend Guardrails:** Enforce quantitative Core Web Vitals (LCP < 1.2s, CLS < 0.05), WCAG 2.2 AA/AAA semantic accessibility, Schema.org JSON-LD compliance, and Playwright multi-viewport responsive testing.
 16. **Airtight Positive Enclosures ("Pink Elephant" Rule):** Replace long negative constraint lists with strict positive operational perimeters (`ONLY modify [Target/Module]`) to prevent attention-drift in deep context windows.
 17. **Sterile / Clinical Vocabulary Mandate:** Eradicate aggressive verbs (`kill`, `amputate`, `sabotage`, `destroy`) from prompts and policies. Use clinical equivalents (`terminate PID`, `prune code`, `mutate test logic`, `purge cache`) to prevent false-positive safety classifier trips in Google Cloud VMs.

package/JULES_RULES_TEMPLATE.md

@@ -58,7 +58,7 @@ Jules automatically infers test and build verification commands via `scripts/com
 - **Minimal Interference**: Preserve existing function signatures, comments, and style conventions.
 - **No Token Bloat**: Exclude lockfiles, minified bundles, and binary assets from diff representations.
 - **Google Labs Exploration Budget Protocol**: Execute complex multi-step tasks across 3 discrete phases: (1) Discovery & Symbol Tracing (silent inspection, write NO code), (2) Oracle & Test Formulation, and (3) Surgical Implementation & Verification.
-- **Critic Agent Steering (Adversarial Pre-Review)**: Jules' internal Critic Agent evaluates proposed patches for edge-case regressions, $O(n^2)$ bottlenecks, unhandled parameters, and layout shifts (CLS) prior to final PR submission.
+- **Critic Agent Steering (Adversarial Pre-Review)**: Jules' internal Critic Agent evaluates proposed patches for edge-case regressions, $O(n^2)$ bottlenecks, unhandled parameters, and layout shifts (CLS) prior to final PR submission. In test modifications, verify deliberate logic mutations turn tests red (mutation falsification).
 - **Airtight Positive Enclosures ("Pink Elephant" Principle)**: Avoid massive negative constraint lists; define explicit positive perimeters (`ONLY modify [Target/Module]`) to eliminate attention distortion and cognitive drag.
 - **Sterile / Clinical Vocabulary Mandate**: Replace aggressive verbs (`kill`, `amputate`, `destroy`) with clinical equivalents (`terminate PID`, `prune code`, `purge state`) to prevent false-positive safety classifier tripwires.
 

package/README.md

@@ -131,7 +131,7 @@ To maximize PR merge rates, dispatch tasks according to deterministic boundaries
 * **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.
 * **Terminal UI & Diagnostic Matrix (`agentctl doctor`):** Interactive terminal dashboard, task sidecar manager, and automated transactional self-repair.
-* **Verified Test Suite:** Tested with **569 unit tests across 81 suites passing in < 10.0s**.
+* **Verified Test Suite:** Tested with **602 unit tests across 83 suites passing in < 10.0s**.
 
 <br/>
 
@@ -148,12 +148,16 @@ To maximize PR merge rates, dispatch tasks according to deterministic boundaries
 | :--- | :--- | :--- | :--- |
 | `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 web task envelopes (`web-cwv`, `web-wcag`, `web-seo`, `web-playwright`, `web-flaky-heal`, `web-i18n`, `web-ai-access`). | `0` (Listed/Synthesized) |
-| `dispatch` | `agentctl dispatch [-p <prompt>] [-f <file>] [-r <role>] [-t <tier>] [--auto-pr] [--repoless] [--dry-run]` | Dispatches autonomous task to the active provider with payload limits and role prompt resolution. | `0` (Dispatched), `1` (Error) |
+| `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) |
+| `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) |
 | `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. | `0` (Complete) |
+| `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]` | Runs security, secret scanning, and verification gates against working tree or branch. | `0` (Approved), `3` (Scope), `5` (Diff >75K), `6` (Secret) |
+| `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) |
+| `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) |
 | `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) |
@@ -319,6 +323,7 @@ console.log(classification.tier); // "fast" | "complex"
 
 | Feature | Module / Command | Architectural Description | Status |
 | :--- | :--- | :--- | :---: |
+| **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)* |
 | **Base64 Secret Detection & Budget Fix** | `src/security.mjs`, `src/budget.mjs` | Secret scanner decodes base64 before matching structured patterns (K8s secrets), and `budget reset` preserves confirmed provider sessions. | **v0.37.0** *(Shipped)* |

package/bin/agentctl.mjs

@@ -40,7 +40,7 @@ export function printHelp() {
 Usage: agentctl <command> [options]
 
 Commands:
-  dispatch | create     Dispatch a single task to an AI agent (--role <name>, --tier fast|complex)
+  dispatch | create     Dispatch a single task to an AI agent (--role <name>, --tier fast|complex, --check-premise)
   gate | audit          Run CI security and verification gate against current branch
   queue                 Run pending task queue (--dag, --concurrency <n>)
   swarm                 Run parallel task swarm
@@ -54,12 +54,15 @@ Commands:
   init                  Scaffold .agent/ config and run onboarding wizard
   task create           Interactively author and scope a Jules task envelope (--template <name>, --role <name>, --tier fast|complex)
   task optimize         Linter & optimizer for Jules task prompts (--fix, --json, --web)
-  task template         List and generate web development task templates (--list, --json)
+  task template         List and generate task templates (--list, --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
   handover              Inspect or generate Baton Pass session handover envelopes (list | show | create | prune)
   resume                Resume warm session with human response (--response "<text>")
+  plan approve <id>     Approve pending plan for a Jules session (:approvePlan)
+  session get <id>      Retrieve remote session status from provider API
+  pr harvest            Triage, verify CI, and auto-merge low-risk agent PRs (--auto, --tier r0,r1)
   escalate              Dispatch or manage webhook escalation incidents (--flush, --status, --clear)
   flaky                 Manage Wilson-quarantined tests and dispatch healing swarm (status | heal | reset)
   status                Display queue and system status summary
@@ -69,11 +72,13 @@ Commands:
   harvest               Harvest failure traces and record/quarantine resolution rules
   learning add          Record a system learning rule into .agent/knowledge/
   evidence <action>     Manage cryptographic audit evidence (generate | verify | show)
+  assert                Run declarative zero-dependency verification assertion primitives
   version               Output agentctl version
 
 Options:
   --role, -r            Specify specialist agent role (overseer | bolt | sentinel | janitor)
   --tier                Force routing tier when router.enabled (fast | complex) — see .agent/config.yml router:
+  --check-premise       Verify task goal/oracle passes locally before burning API budget
   --dag                 Execute queue tasks via DAG dependency resolution
   --dry-run, -d         Simulate action without making API calls or modifying git
   --mode, -m            Gate evaluation mode (working-tree | committed | staged)
@@ -81,6 +86,7 @@ Options:
   --source, -s          Specify Jules repository source name
   --branch, -b          Specify target starting branch
   --json, -j            Emit machine-readable JSON output
+  --json-report <path>  Write structured machine-readable JSON diagnostics report
   --help, -h            Show command help
 `);
 }
@@ -147,6 +153,8 @@ async function main() {
           repoless: { type: "boolean" },
           "auto-pr": { type: "boolean" },
           "require-plan-approval": { type: "boolean" },
+          "check-premise": { type: "boolean" },
+          idempotent: { type: "boolean" },
           "dry-run": { type: "boolean", short: "d" },
           json: { type: "boolean", short: "j" },
         },
@@ -177,6 +185,7 @@ async function main() {
         repoless: values.repoless,
         autoPr: values["auto-pr"],
         requirePlanApproval: values["require-plan-approval"],
+        checkPremise: values["check-premise"] || values.idempotent,
       };
 
       try {
@@ -187,15 +196,21 @@ async function main() {
           repoless: values.repoless,
           source: values.source,
           branch: values.branch,
+          checkPremise: values["check-premise"] || values.idempotent,
         });
         if (values.json) {
           console.log(JSON.stringify({ ok: true, session }, null, 2));
         } else {
-          console.log(`\n✅ Task Dispatched Successfully!`);
-          console.log(`   Session ID  : ${session.id}`);
-          console.log(`   Session URL : ${session.url || "N/A"}`);
-          if (session._routeTier) {
-            console.log(`   Router Tier : ${session._routeTier} (${session._routeReason || "n/a"})`);
+          if (session.status === "ALREADY_SATISFIED" || session.skipped) {
+            console.log(`\n⚡ Task Already Satisfied (skipped dispatch):`);
+            console.log(`   Reason: ${session.reason || "Verification oracle already passing on base branch."}`);
+          } else {
+            console.log(`\n✅ Task Dispatched Successfully!`);
+            console.log(`   Session ID  : ${session.id}`);
+            console.log(`   Session URL : ${session.url || "N/A"}`);
+            if (session._routeTier) {
+              console.log(`   Router Tier : ${session._routeTier} (${session._routeReason || "n/a"})`);
+            }
           }
         }
         process.exit(0);
@@ -224,6 +239,7 @@ async function main() {
           fix: { type: "boolean" },
           "allow-protected": { type: "boolean" },
           json: { type: "boolean", short: "j" },
+          "json-report": { type: "string" },
           "dry-run": { type: "boolean", short: "d" },
         },
         allowPositionals: true,
@@ -241,6 +257,7 @@ async function main() {
         mode: selectedMode,
         fix: values.fix,
         allowProtected: values["allow-protected"],
+        jsonReport: values["json-report"],
       });
 
       if (values.json) {
@@ -285,6 +302,93 @@ async function main() {
       break;
     }
 
+    case "assert": {
+      const { runAssertion, parseYaml } = await import("../index.mjs");
+      const { values } = parseArgs({
+        args: args.slice(1),
+        options: {
+          dir: { type: "string", short: "d" },
+          file: { type: "string", short: "f" },
+          targets: { type: "string", short: "t" },
+          patterns: { type: "string", short: "p" },
+          "patterns-file": { type: "string" },
+          "max-bytes": { type: "string" },
+          "max-kb": { type: "string" },
+          "max-mb": { type: "string" },
+          gzip: { type: "boolean" },
+          config: { type: "string", short: "c" },
+          json: { type: "boolean", short: "j" },
+          "json-report": { type: "string" },
+        },
+        allowPositionals: true,
+      });
+
+      let stageConfig = {};
+      if (values.config && existsSync(values.config)) {
+        const raw = readFileSync(values.config, "utf-8");
+        stageConfig = parseYaml(raw);
+      } else {
+        let assertType = "dir-size";
+        if (values.file) assertType = "file-size";
+        else if (values.patterns || values["patterns-file"] || values.targets) assertType = "file-patterns";
+        else if (values.dir) assertType = "dir-size";
+
+        stageConfig = {
+          assert: assertType,
+          path: values.dir || values.file,
+          targets: values.targets ? values.targets.split(",").map((s) => s.trim()) : undefined,
+          patterns: values.patterns ? values.patterns.split(",").map((s) => s.trim()) : undefined,
+          patternsFile: values["patterns-file"],
+          maxBytes: values["max-bytes"] ? Number(values["max-bytes"]) : undefined,
+          maxKb: values["max-kb"] ? Number(values["max-kb"]) : undefined,
+          maxMb: values["max-mb"] ? Number(values["max-mb"]) : undefined,
+          gzip: values.gzip,
+        };
+      }
+
+      const result = runAssertion(stageConfig, root);
+      if (values["json-report"]) {
+        const { exportJsonReport, generateEvidenceManifest } = await import("../src/evidence.mjs");
+        const dummyManifest = generateEvidenceManifest(root, {
+          taskId: "CLI-ASSERT",
+          title: "Ad-hoc Assertion",
+          executionRecords: [
+            {
+              id: result.assertionType,
+              kind: "assert",
+              assert: result.assertionType,
+              exitCode: result.status,
+              durationMs: result.metrics?.durationMs || 0,
+              diagnostics: result.diagnostics,
+              metrics: result.metrics,
+            },
+          ],
+          diagnostics: result.diagnostics,
+          metrics: result.metrics,
+          ok: result.ok,
+        });
+        exportJsonReport(dummyManifest, values["json-report"]);
+      }
+
+      if (values.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        if (result.ok) {
+          console.log(`\n✅ Assertion [${result.assertionType}] PASSED (${result.metrics?.durationMs || 0}ms)`);
+          if (result.metrics?.measuredBytes !== undefined) {
+            console.log(`   Measured : ${result.metrics.measuredBytes} bytes${result.metrics.gzip ? " (gzipped)" : ""}`);
+          }
+        } else {
+          console.error(`\n❌ Assertion [${result.assertionType}] FAILED (Exit 1)`);
+          for (const d of result.diagnostics) {
+            console.error(`   - ${d}`);
+          }
+        }
+      }
+      process.exit(result.status);
+      break;
+    }
+
     case "queue": {
       const { values } = parseArgs({
         args: args.slice(1),
@@ -643,7 +747,7 @@ async function main() {
           if (values.json) {
             console.log(JSON.stringify({ ok: true, templates }, null, 2));
           } else {
-            console.log(`\n🌐 Available Web Development Task Templates`);
+            console.log(`\n📋 Available Task Templates & Envelopes`);
             console.log(`--------------------------------------------------`);
             templates.forEach((t) => {
               console.log(`  • ${t.id.padEnd(16)} [${t.category}]`);
@@ -977,6 +1081,160 @@ async function main() {
       break;
     }
 
+    case "plan": {
+      const subAction = args[1];
+      if (subAction === "approve") {
+        const sessionId = args[2];
+        const { values, positionals } = parseArgs({
+          args: args.slice(2),
+          options: {
+            "dry-run": { type: "boolean", short: "d" },
+            json: { type: "boolean", short: "j" },
+          },
+          allowPositionals: true,
+        });
+        const targetSessionId = sessionId && !sessionId.startsWith("-") ? sessionId : positionals?.[0];
+        if (!targetSessionId) {
+          console.error("Error: Session ID is required for agentctl plan approve <sessionId>.");
+          process.exit(1);
+        }
+        const { createProvider } = await import("../src/provider.mjs");
+        const provider = createProvider(config.provider || "jules", config);
+        try {
+          const res = await provider.approvePlan(targetSessionId, { root, dryRun: values["dry-run"] });
+          if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+          } else {
+            console.log(`\n✅ Plan Approved Successfully!`);
+            console.log(`   Session ID : ${res.id}`);
+            console.log(`   Status     : ${res.status}\n`);
+          }
+          process.exit(0);
+        } catch (err) {
+          console.error(`❌ Plan Approval Failed: ${err.message}`);
+          process.exit(1);
+        }
+      }
+      console.error(`Error: Unknown plan subcommand '${subAction}'. Use approve.`);
+      process.exit(1);
+      break;
+    }
+
+    case "approve": {
+      const sessionId = args[1];
+      const { values, positionals } = parseArgs({
+        args: args.slice(1),
+        options: {
+          "dry-run": { type: "boolean", short: "d" },
+          json: { type: "boolean", short: "j" },
+        },
+        allowPositionals: true,
+      });
+      const targetSessionId = sessionId && !sessionId.startsWith("-") ? sessionId : positionals?.[0];
+      if (!targetSessionId) {
+        console.error("Error: Session ID is required for agentctl approve <sessionId>.");
+        process.exit(1);
+      }
+      const { createProvider } = await import("../src/provider.mjs");
+      const provider = createProvider(config.provider || "jules", config);
+      try {
+        const res = await provider.approvePlan(targetSessionId, { root, dryRun: values["dry-run"] });
+        if (values.json) {
+          console.log(JSON.stringify(res, null, 2));
+        } else {
+          console.log(`\n✅ Plan Approved Successfully!`);
+          console.log(`   Session ID : ${res.id}`);
+          console.log(`   Status     : ${res.status}\n`);
+        }
+        process.exit(0);
+      } catch (err) {
+        console.error(`❌ Plan Approval Failed: ${err.message}`);
+        process.exit(1);
+      }
+      break;
+    }
+
+    case "session": {
+      const subAction = args[1];
+      if (subAction === "get" || subAction === "status") {
+        const sessionId = args[2];
+        const { values, positionals } = parseArgs({
+          args: args.slice(2),
+          options: {
+            "dry-run": { type: "boolean", short: "d" },
+            json: { type: "boolean", short: "j" },
+          },
+          allowPositionals: true,
+        });
+        const targetSessionId = sessionId && !sessionId.startsWith("-") ? sessionId : positionals?.[0];
+        if (!targetSessionId) {
+          console.error("Error: Session ID is required for agentctl session get <sessionId>.");
+          process.exit(1);
+        }
+        const { createProvider } = await import("../src/provider.mjs");
+        const provider = createProvider(config.provider || "jules", config);
+        try {
+          const res = await provider.getSession(targetSessionId, { root, dryRun: values["dry-run"] });
+          if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+          } else {
+            console.log(`\n📋 Remote Session Status:`);
+            console.log(`   Session ID : ${res.id}`);
+            console.log(`   Status     : ${res.status}\n`);
+          }
+          process.exit(0);
+        } catch (err) {
+          console.error(`❌ Session Retrieval Failed: ${err.message}`);
+          process.exit(1);
+        }
+      }
+      console.error(`Error: Unknown session subcommand '${subAction}'. Use get.`);
+      process.exit(1);
+      break;
+    }
+
+    case "pr": {
+      const subAction = args[1];
+      if (subAction === "harvest") {
+        const { harvestPullRequests, formatHarvestTable } = await import("../src/ops/pr-harvest.mjs");
+        const { values } = parseArgs({
+          args: args.slice(2),
+          options: {
+            tier: { type: "string" },
+            limit: { type: "string" },
+            auto: { type: "boolean" },
+            merge: { type: "boolean" },
+            "dry-run": { type: "boolean", short: "d" },
+            json: { type: "boolean", short: "j" },
+          },
+          allowPositionals: true,
+        });
+
+        const limit = values.limit ? parseInt(values.limit, 10) : 50;
+        try {
+          const res = await harvestPullRequests(root, {
+            tier: values.tier,
+            limit,
+            auto: values.auto || values.merge,
+            dryRun: values["dry-run"],
+          });
+
+          if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+          } else {
+            console.log(formatHarvestTable(res));
+          }
+          process.exit(0);
+        } catch (err) {
+          console.error(`❌ PR Harvest Failed: ${err.message}`);
+          process.exit(1);
+        }
+      }
+      console.error(`Error: Unknown PR subcommand '${subAction}'. Use harvest.`);
+      process.exit(1);
+      break;
+    }
+
     case "escalate": {
       const {
         dispatchEscalation,

package/index.mjs

@@ -149,8 +149,20 @@ export {
   verifyEvidenceManifest,
   generateEvidenceMarkdown,
   computeEvidenceHash,
+  exportJsonReport,
 } from "./src/evidence.mjs";
 
+// Declarative Assertion Primitives
+export {
+  assertDirSize,
+  assertFileSize,
+  assertFilePatterns,
+  assertFileExists,
+  runAssertion,
+  formatBytes,
+  resolveBytesLimit,
+} from "./src/assertions.mjs";
+
 export {
   resolveDailyLimit,
   budgetStatus,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jules-orchestrator-kit",
-  "version": "0.38.1",
+  "version": "0.39.0",
   "description": "Zero-dependency safety gatekeeper, test oracle generator, and multi-agent coordination protocol for Google Jules (jules) autonomous agents.",
   "repository": {
     "type": "git",