jules-orchestrator-kit 0.41.1 → 0.42.0

package/README.md

@@ -143,7 +143,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, 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 **706 unit tests across 85 suites passing in < 10.0s**.
+* **Verified Test Suite:** Tested with **717 unit tests across 85 suites passing in < 10.0s**.
 
 <br/>
 
@@ -169,7 +169,8 @@ To maximize PR merge rates, dispatch tasks according to deterministic boundaries
 | `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 [--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) |
+| `check` / `gate` / `audit`| `agentctl check [--mode working-tree] [--fix] [--json] [--json-report <path>]` | Runs security, secret scanning, rules budget audit, and tiered verification gates (with declarative assertion support) against working tree or branch. | `0` (Approved), `1` (Budget/Arg), `3` (Scope), `4` (Verify), `5` (Diff >75K), `6` (Secret), `8` (Flaky) |
+| `rules` | `agentctl rules <check\|compile> [--out <path>] [--json]` | Audits instruction files against character/line budgets or compiles unified rules block with SHA-256 and length anti-truncation sentinels. | `0` (Valid/Compiled), `1` (Violations) |
 | `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) |

package/bin/agentctl.mjs

@@ -41,7 +41,9 @@ Usage: agentctl <command> [options]
 
 Commands:
   dispatch | create     Dispatch a single task to an AI agent (--role <name>, --tier fast|complex, --check-premise)
+  check                 Run all-in-one CI security, rules, and stack verification gate
   gate | audit          Run CI security and verification gate against current branch
+  rules <action>        Audit rule token budgets or compile rule sentinels (check | compile)
   queue                 Run pending task queue (--dag, --concurrency <n>)
   swarm                 Run parallel task swarm
   mcp                   Start stdio Model Context Protocol (MCP) server
@@ -343,6 +345,7 @@ async function main() {
       break;
     }
 
+    case "check":
     case "gate":
     case "audit": {
       const { values } = parseArgs({
@@ -1888,6 +1891,76 @@ async function main() {
       break;
     }
 
+    case "rules": {
+      const subcmd = args[1] || "check";
+      const { checkRulesBudget, compileRules } = await import("../src/rules_budget.mjs");
+
+      if (subcmd === "check") {
+        const { values } = parseArgs({
+          args: args.slice(2),
+          options: {
+            json: { type: "boolean", short: "j" },
+            "max-chars": { type: "string" },
+            "max-lines": { type: "string" },
+          },
+          allowPositionals: true,
+        });
+
+        const res = checkRulesBudget(root, {
+          maxChars: values["max-chars"] ? Number(values["max-chars"]) : undefined,
+          maxLines: values["max-lines"] ? Number(values["max-lines"]) : undefined,
+        });
+
+        if (values.json) {
+          console.log(JSON.stringify(res, null, 2));
+        } else {
+          console.log("\n📏 agentctl Rules Budget & Line Audit");
+          console.log("-----------------------------------------------------");
+          if (res.ok) {
+            console.log("✅ All agent rule files are within safe character (<10,000) and line (<250) limits.");
+          } else {
+            console.log("❌ RULES BUDGET VIOLATIONS DETECTED:");
+            for (const v of res.violations) {
+              console.log(`  - ${v.path}: ${v.reason}`);
+            }
+            console.log("\n💡 Remediation: Trim prose rules or convert textual learnings into AST lints / assertions.");
+          }
+          console.log("-----------------------------------------------------\n");
+        }
+        process.exit(res.ok ? 0 : 1);
+      } else if (subcmd === "compile") {
+        const { values } = parseArgs({
+          args: args.slice(2),
+          options: {
+            out: { type: "string", short: "o" },
+            json: { type: "boolean", short: "j" },
+          },
+          allowPositionals: true,
+        });
+
+        const res = compileRules(root);
+        if (values.out) {
+          const { writeFileSync } = await import("node:fs");
+          const { resolve } = await import("node:path");
+          writeFileSync(resolve(root, values.out), res.compiled, "utf-8");
+          if (values.json) {
+            console.log(JSON.stringify({ ok: true, out: values.out, sha256: res.sha256, bodyLen: res.bodyLen, sources: res.sources }, null, 2));
+          } else {
+            console.log(`✅ Compiled ${res.sources.length} rule source(s) into ${values.out} (SHA-256: ${res.sha256.slice(0, 12)}..., ${res.bodyLen} bytes)`);
+          }
+        } else if (values.json) {
+          console.log(JSON.stringify(res, null, 2));
+        } else {
+          console.log(res.compiled);
+        }
+        process.exit(0);
+      } else {
+        console.error(`Unknown rules action: "${subcmd}". Usage: agentctl rules [check | compile]`);
+        process.exit(1);
+      }
+      break;
+    }
+
     default:
       console.error(`Unknown command: ${command}`);
       printHelp();

package/package.json

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

package/src/scaffold.mjs

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readdirSync, copyFileSync, readFileSync, appendFileSync, writeFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { detectPolyglotStack, detectEdgeRuntime } from "./stack-detector.mjs";
 
 const KIT_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -77,6 +78,136 @@ function copyDir(srcDir, destDir, force) {
   return written;
 }
 
+/**
+ * Generate stack-tailored contract templates (SPEC.md, CONSTRAINTS.md, DESIGN.md).
+ *
+ * @param {string} root - Project root
+ * @param {{ force?: boolean }} [options]
+ * @returns {string[]} Created contract file names
+ */
+export function scaffoldContracts(root = process.cwd(), options = {}) {
+  const force = Boolean(options.force);
+  const created = [];
+
+  const specPath = join(root, "SPEC.md");
+  if (!existsSync(specPath) || force) {
+    const specContent = `# SPEC — System & Product Contract
+
+## Product
+- Brief 1–2 sentence description of the system and target users.
+
+## Core Loop
+- Step-by-step lifecycle from input/event to final response/artifact.
+
+## Goals
+- [Goal 1: Core invariant functionality that MUST work]
+- [Goal 2: Performance, throughput, or latency targets]
+- [Goal 3: Test coverage & reliability criteria]
+
+## Non-Goals
+- [Explicit out-of-scope feature or abstraction]
+- [Out-of-scope third-party dependencies or integrations]
+
+## Definition of Done
+- All verification test suites pass cleanly with 0 errors
+- Zero security vulnerabilities and zero leaked secrets
+- Diff size stays within the configured limit (<= 75 KB)
+`;
+    writeFileSync(specPath, specContent, "utf-8");
+    created.push("SPEC.md");
+  }
+
+  const constraintsPath = join(root, "CONSTRAINTS.md");
+  if (!existsSync(constraintsPath) || force) {
+    const edgeInfo = detectEdgeRuntime(root);
+    const stackInfo = detectPolyglotStack(root);
+
+    let constraintsContent = "";
+    if (edgeInfo.edgePlatform === "cloudflare") {
+      constraintsContent = `# CONSTRAINTS — Cloudflare Workers / workerd
+
+## Runtime Invariants
+- Zero unbundled \`node:*\` imports in \`src/\` (rely on standard Web APIs or polyfilled modules)
+- Bundle size: Max 10 MB total
+- RAM memory limit: 128 MB
+- Database & KV: Batch operations via \`db.batch([])\`, zero unbounded query loops
+- Static content: Zero client-side JavaScript for static content
+`;
+    } else if (stackInfo.stack === "cargo") {
+      constraintsContent = `# CONSTRAINTS — Rust Architecture
+
+## Runtime & Safety Invariants
+- Zero \`unsafe\` blocks unless explicitly audited and documented
+- No unhandled \`.unwrap()\` or \`.expect()\` in production/request-handling code paths
+- Clippy compliance: \`cargo clippy -- -D warnings\` must pass with 0 warnings
+- Strict error propagation using \`Result<T, E>\` / \`thiserror\` / \`anyhow\`
+`;
+    } else if (stackInfo.stack === "go") {
+      constraintsContent = `# CONSTRAINTS — Go Architecture
+
+## Runtime & Safety Invariants
+- Deterministic builds: \`CGO_ENABLED=0\`
+- Explicit error handling: Never discard \`err\` returns (\`_ = err\` is strictly prohibited)
+- Data race free: \`go test -race ./...\` must pass with 0 failures
+- Strict struct tagging and deterministic serialization
+`;
+    } else if (["python", "poetry", "uv", "pipenv"].includes(stackInfo.stack)) {
+      constraintsContent = `# CONSTRAINTS — Python Architecture
+
+## Runtime & Safety Invariants
+- Strict type annotations on all function signatures (\`mypy --strict\` passes)
+- Zero unpinned dependencies in production manifests
+- Lint & format cleanly with \`ruff\` or \`flake8\`/\`black\`
+- Pytest suite passes 100% cleanly
+`;
+    } else {
+      constraintsContent = `# CONSTRAINTS — Technical Invariants
+
+## Architecture & Code Quality
+- Zero third-party runtime dependencies in core orchestration/shared packages
+- Diff Payload Budget: Keep diffs under 75 KB to prevent truncation
+- Strict Test Lock: Never weaken assertions or delete failing tests to force green status
+- Cross-Platform: Normalize all filesystem paths to POSIX slashes (\`/\`)
+`;
+    }
+
+    writeFileSync(constraintsPath, constraintsContent, "utf-8");
+    created.push("CONSTRAINTS.md");
+  }
+
+  // If web/UI stack is detected (Astro, Next, Svelte, Vue, React, Tailwind), scaffold DESIGN.md
+  const isWeb = existsSync(join(root, "astro.config.mjs")) ||
+    existsSync(join(root, "next.config.js")) ||
+    existsSync(join(root, "next.config.mjs")) ||
+    existsSync(join(root, "svelte.config.js")) ||
+    existsSync(join(root, "tailwind.config.js")) ||
+    existsSync(join(root, "tailwind.config.mjs")) ||
+    existsSync(join(root, "tailwind.config.ts"));
+
+  const designPath = join(root, "DESIGN.md");
+  if (isWeb && (!existsSync(designPath) || force)) {
+    const designContent = `# DESIGN — Visual Tokens & Design System
+
+## Typography
+- Headings: Clean sans-serif / geometric font
+- Body: Readable system font / sans-serif
+
+## Tokens (@theme)
+- Consistent spacing scale (4px, 8px, 16px, 24px, 32px, 48px)
+- Strict color tokens for surfaces, text, and borders
+
+## Hard UI Rules
+- Zero client-side JS for purely static content
+- Accessible contrast ratios (WCAG AA minimum 4.5:1)
+- Explicit hover, focus-visible, and active states on all interactive elements
+`;
+    writeFileSync(designPath, designContent, "utf-8");
+    created.push("DESIGN.md");
+  }
+
+  return created;
+}
+
 /**
  * Scaffold the repository assets the CLI's documented features depend on.
  *
@@ -90,7 +221,7 @@ function copyDir(srcDir, destDir, force) {
  * routine way to pick up new presets and must not overwrite local edits.
  *
  * @param {string} [root=process.cwd()]
- * @param {{ force?: boolean }} [options]
+ * @param {{ force?: boolean, contracts?: boolean }} [options]
  * @returns {{ created: string[], gitignore: string[] }}
  */
 export function scaffoldRepoAssets(root = process.cwd(), options = {}) {
@@ -128,6 +259,12 @@ export function scaffoldRepoAssets(root = process.cwd(), options = {}) {
     created.push(".agent/workflows/");
   }
 
+  // Scaffold contract documents (SPEC.md, CONSTRAINTS.md, DESIGN.md)
+  if (options.contracts !== false) {
+    const contracts = scaffoldContracts(root, options);
+    created.push(...contracts);
+  }
+
   // isTaskFile() skips README.md, so the queue can carry its own explanation
   // without the runner mistaking it for a task envelope.
   const queueReadme = join(queueDir, "README.md");