jules-orchestrator-kit 0.41.0 → 0.42.0

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:
@@ -131,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 **671 unit tests across 84 suites passing in < 10.0s**.
+* **Verified Test Suite:** Tested with **717 unit tests across 85 suites passing in < 10.0s**.
 
 <br/>
 
@@ -146,18 +158,19 @@ 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) |
+| `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 [--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 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 [-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. | `0` (Dispatched), `1` (Error) |
+| `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] [--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) |
+| `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) |
@@ -356,6 +369,8 @@ const result = await fast.dispatch({ prompt: "Fix a typo." }, { root: process.cw
 
 | 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)* |

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
@@ -76,6 +78,9 @@ Commands:
   version               Output agentctl version
 
 Options:
+  --prompt, -p          Task prompt text — dispatch, task create and task optimize
+                        also accept it as a positional argument
+  --prompt-file, -f     Read the prompt from a file (-f is --fix on task optimize)
   --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
@@ -91,6 +96,96 @@ Options:
 `);
 }
 
+/**
+ * Resolve the prompt text a command was given, from any of the three forms.
+ *
+ * The commands that take a prompt each accepted a different subset: `dispatch`
+ * took a flag, a file or a positional; `task create` took only `--prompt`; and
+ * `task optimize` took only a positional. The form an operator learned on one
+ * command then failed on the next — loudly on `task create "do the thing"`,
+ * which reported a missing prompt while holding one, and silently on
+ * `task optimize --prompt "..."`, which optimised an empty string.
+ *
+ * @param {Record<string, unknown>} values Parsed flags.
+ * @param {string[]} [positionals] Remaining free arguments.
+ * @returns {string} The prompt, or "" when none was supplied.
+ */
+function resolvePromptInput(values, positionals = []) {
+  const file = values["prompt-file"] || values.file;
+  if (file) {
+    if (!existsSync(file)) {
+      console.error(`Error: prompt file not found: ${file}`);
+      process.exit(1);
+    }
+    return readFileSync(file, "utf-8");
+  }
+  if (values.prompt) return String(values.prompt);
+  return positionals.join(" ").trim();
+}
+
+/**
+ * Renders the outcome of a queue or swarm run and returns the exit code.
+ *
+ * The per-task failures used to be dropped on the floor. A run where every
+ * task was rejected — no API key is the common one — still printed
+ * "Processed 3 task(s)." and exited 0, so neither an operator nor a CI job
+ * could tell a dispatched queue from a dead one. The failures were already in
+ * the result object the whole time; only `--json` ever showed them.
+ *
+ * @param {{ processed?: number, results?: Array<{file?: string, ok?: boolean, status?: string, error?: string}> }} outcome
+ * @returns {number} 0 when every task succeeded, 1 when any failed.
+ */
+function reportRunOutcome(outcome) {
+  const items = Array.isArray(outcome?.results) ? outcome.results : [];
+  const failed = items.filter((r) => r && r.ok === false);
+  const succeeded = items.length - failed.length;
+
+  console.log(`\nProcessed ${outcome?.processed ?? items.length} task(s): ${succeeded} ok, ${failed.length} failed.`);
+
+  if (failed.length > 0) {
+    console.error(`\n❌ ${failed.length} task(s) did not dispatch:`);
+    for (const f of failed) {
+      const reason = f.error || f.status || "Unknown error";
+      console.error(`   - ${f.file || f.taskId || "task"}: ${reason}`);
+    }
+    // A failed task is left in the queue rather than moved to completed/, so
+    // fixing the cause and re-running is the whole recovery procedure.
+    console.error(`\n   These tasks are still queued. Fix the cause above and re-run.`);
+    return 1;
+  }
+  if (items.some((r) => r && r.dryRun)) {
+    console.log(`   Dry run — no provider call was made and nothing was dispatched.`);
+  }
+  return 0;
+}
+
+/**
+ * Render the stage, exit code and captured output of a failed verify phase.
+ *
+ * VERIFY is the one gate phase whose failure the operator has to fix in their
+ * own code, and it was the only one that printed nothing beyond "❌ FAIL" —
+ * the command's output was captured, hashed into the evidence manifest, and
+ * then discarded before anyone could read it.
+ *
+ * @param {{ stageId?: string, command?: string|null, exitCode?: number|null, stdout?: string, stderr?: string, diagnostics?: string[] }} failure
+ */
+const VERIFY_OUTPUT_TAIL_LINES = 20;
+
+function printVerifyFailure(failure) {
+  const exit = failure.exitCode === null || failure.exitCode === undefined ? "n/a" : failure.exitCode;
+  console.log(`     - Stage: ${failure.stageId || "verify"} (exit ${exit})`);
+  if (failure.command) console.log(`     - Command: ${failure.command}`);
+  for (const d of failure.diagnostics || []) console.log(`     - ${d}`);
+
+  // stderr is where a failing suite says what it expected; stdout is the
+  // fallback for the runners that report everything there.
+  const output = (failure.stderr || "").trim() || (failure.stdout || "").trim();
+  if (!output) return;
+  const lines = output.split("\n");
+  const tail = lines.slice(-VERIFY_OUTPUT_TAIL_LINES);
+  console.log(`     - Output${tail.length < lines.length ? ` (last ${VERIFY_OUTPUT_TAIL_LINES} of ${lines.length} lines)` : ""}:`);
+  for (const line of tail) console.log(`         ${line}`);
+}
 
 async function main() {
   if (command === "--help" || command === "-h") {
@@ -140,7 +235,7 @@ async function main() {
   switch (command) {
     case "dispatch":
     case "create": {
-      const { values } = parseArgs({
+      const { values, positionals } = parseArgs({
         args: args.slice(1),
         options: {
           title: { type: "string", short: "t" },
@@ -162,20 +257,28 @@ async function main() {
         allowPositionals: true,
       });
 
-      let promptContent = values.prompt || "";
-      if (values["prompt-file"] && existsSync(values["prompt-file"])) {
-        promptContent = readFileSync(values["prompt-file"], "utf-8");
-      }
-
-      if (!promptContent && args[1] && !args[1].startsWith("-")) {
-        promptContent = args.slice(1).join(" ");
-      }
-
+      const promptContent = resolvePromptInput(values, positionals);
       if (!promptContent) {
-        console.error("Error: --prompt or --prompt-file is required.");
+        console.error("Error: a prompt is required — pass it as --prompt, --prompt-file, or a positional argument.");
         process.exit(1);
       }
 
+      // `task create --role` has always rejected a role it cannot resolve;
+      // `dispatch --role` used to drop it without a word and hand the work to a
+      // generic agent, so the two commands disagreed about what the same flag
+      // means. An explicitly typed role is a statement of intent — failing here
+      // is the only way the operator learns the prompt file is missing.
+      if (values.role) {
+        const { resolveRolePrompt } = await import("../src/role-resolver.mjs");
+        if (!resolveRolePrompt(root, values.role, { config })) {
+          console.error(
+            `Error: Unknown agent role '${values.role}'. Expected matching prompt file in .agent/prompts/ (e.g. Overseer, Bolt, Sentinel, Janitor).`
+          );
+          console.error(`   Run 'agentctl init' to scaffold the shipped role prompts.`);
+          process.exit(1);
+        }
+      }
+
       const task = {
         title: values.title || "CLI Dispatch Task",
         prompt: promptContent,
@@ -206,6 +309,20 @@ async function main() {
           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 if (values["dry-run"]) {
+            // The dry run reached the provider adapter and stopped short of the
+            // call. Printing the same "Dispatched Successfully!" banner as a
+            // real dispatch made the two indistinguishable in a terminal, so a
+            // rehearsal read as work in flight and the operator waited for a
+            // session that was never going to exist.
+            console.log(`\n🧪 Dry Run — nothing was dispatched.`);
+            console.log(`   Title       : ${task.title}`);
+            console.log(`   Provider    : ${session.provider || config.provider || "jules"}`);
+            if (task.role) console.log(`   Role        : ${task.role}`);
+            if (session._routeTier) {
+              console.log(`   Router Tier : ${session._routeTier} (${session._routeReason || "n/a"})`);
+            }
+            console.log(`\n   Re-run without --dry-run to dispatch for real.`);
           } else {
             console.log(`\n✅ Task Dispatched Successfully!`);
             console.log(`   Session ID  : ${session.id}`);
@@ -228,6 +345,7 @@ async function main() {
       break;
     }
 
+    case "check":
     case "gate":
     case "audit": {
       const { values } = parseArgs({
@@ -274,13 +392,32 @@ async function main() {
             p.violations.forEach((v) => console.log(`     - Violation: ${v.file} (Rule: ${v.rule})`));
           }
           if (p.findings) {
-            p.findings.forEach((f) => console.log(`     - Finding: ${f.id} at line ${f.line}`));
+            p.findings.forEach((f) => console.log(`     - [${f.severity}] ${f.type}: ${f.description}`));
+          }
+          if (!p.ok && p.failure) {
+            printVerifyFailure(p.failure);
           }
         }
         console.log(`-----------------------------------------------------`);
         console.log(`Overall Result: ${res.ok ? "APPROVED (Exit 0)" : `REJECTED (Exit ${res.code})`}\n`);
         if (!res.ok) {
-          if (res.code === 3) {
+          const failedPhase = res.phases.find((p) => !p.ok)?.phase;
+          // Exit 3 is also what a strictTestLock tamper verdict returns, so the
+          // code alone cannot pick the hint — a scope remediation for a rewritten
+          // test file sends the operator to the wrong flag entirely.
+          if (res.repairs) {
+            console.log(`💡 Remediation Hint (Exit 4 OODA Repair Exhausted):`);
+            console.log(`   • Automated self-repair could not pass tests cleanly.`);
+            console.log(`   • Review error fingerprints via: agentctl doctor\n`);
+          } else if (res.flakyVerdict?.verdict === "QUARANTINED") {
+            console.log(`💡 Remediation Hint (Exit 8 Flaky Test Quarantined):`);
+            console.log(`   • This command has alternated between pass and fail across recent runs.`);
+            console.log(`   • Fix the test's non-determinism — re-running will not clear the verdict.\n`);
+          } else if (failedPhase === "verify" || failedPhase === "evidence") {
+            console.log(`💡 Remediation Hint (Exit ${res.code} Verification Failed):`);
+            console.log(`   • The stage above exited non-zero. Reproduce it locally, then re-run the gate.`);
+            console.log(`   • To let agentctl attempt the repair loop itself, pass: agentctl gate --fix\n`);
+          } else if (res.code === 3) {
             console.log(`💡 Remediation Hint (Exit 3 Scope Violation):`);
             console.log(`   • To allow protected files in this run, pass: agentctl gate --allow-protected`);
             console.log(`   • Or remove protected/denied paths from the diff before dispatching.\n`);
@@ -292,10 +429,6 @@ async function main() {
             console.log(`💡 Remediation Hint (Exit 6 Secret Leak Prevented):`);
             console.log(`   • High-entropy credential or secret detected in patch.`);
             console.log(`   • Scrub credential from source and rotate any exposed keys immediately.\n`);
-          } else if (res.code === 4) {
-            console.log(`💡 Remediation Hint (Exit 4 OODA Repair Exhausted):`);
-            console.log(`   • Automated self-repair could not pass tests cleanly.`);
-            console.log(`   • Review error fingerprints via: agentctl doctor\n`);
           }
         }
       }
@@ -417,9 +550,10 @@ async function main() {
         });
         if (values.json) {
           console.log(JSON.stringify(results, null, 2));
-        } else {
-          console.log(`\nProcessed ${results.processed || results.results?.length || 0} task(s).`);
+          const anyFailed = (results.results || []).some((r) => r && r.ok === false);
+          process.exit(anyFailed ? 1 : 0);
         }
+        process.exit(reportRunOutcome(results));
       }
       process.exit(0);
       break;
@@ -439,8 +573,7 @@ async function main() {
         prompt: readFileSync(join(queueDir, f), "utf-8"),
       }));
       const results = await run(tasks, { root, config, concurrency: config.limits.concurrency || 3 });
-      console.log(`Swarm completed ${results.length} tasks.`);
-      process.exit(0);
+      process.exit(reportRunOutcome(results));
       break;
     }
 
@@ -679,6 +812,7 @@ async function main() {
           tier: { type: "string", short: "t" },
           json: { type: "boolean", short: "j" },
           "dry-run": { type: "boolean", short: "d" },
+          force: { type: "boolean", short: "f" },
         },
         allowPositionals: true,
       });
@@ -694,13 +828,38 @@ async function main() {
         allowDefaults: true,
       });
 
+      // The wizard writes the manifest; the assets the CLI's documented
+      // features actually need — AGENTS.md, the role prompts, the guardrails,
+      // the gitignore entries — used to be scaffolded only by the separate
+      // `jules-init` binary that the README's quickstart never mentions.
+      const { scaffoldRepoAssets } = await import("../src/scaffold.mjs");
+      const scaffold = scaffoldRepoAssets(root, { force: values.force });
+
       if (values.json) {
-        console.log(JSON.stringify(res, null, 2));
+        console.log(JSON.stringify({ ...res, scaffold }, null, 2));
       } else {
         console.log(`✅ Onboarding complete! Manifest generated at ${res.configPath}`);
         console.log(`   Tier: ${res.plan.tier.toUpperCase()} (${res.plan.limits.concurrency} worker(s), ${res.plan.limits.daily_tasks} daily tasks)`);
         console.log(`   Verification Test Command : "${res.plan.verify.test}"`);
         console.log(`   Active Presets            : ${res.plan.presets.join(", ")}`);
+        for (const item of scaffold.created) {
+          console.log(`   Scaffolded                : ${item}`);
+        }
+        if (scaffold.gitignore.length > 0) {
+          console.log(`   Ignored runtime state     : ${scaffold.gitignore.length} entries added to .gitignore`);
+        }
+
+        // `.agent/config.yml` and `.agent/jules.yml` are both on the gate's deny
+        // list, by design — the agent must not edit its own rules. Leaving them
+        // uncommitted meant the very first `agentctl gate` rejected the working
+        // tree for files init had just written, which reads as the tool
+        // catching the user cheating on step three.
+        console.log(`\n   Commit the manifest so the gate does not read it as an agent edit:`);
+        console.log(`     git add .agent AGENTS.md .gitignore && git commit -m "chore: add agent config"`);
+
+        const { resolveNextStep, renderNextStep } = await import("../src/ops/next-step.mjs");
+        const next = resolveNextStep(root);
+        console.log(renderNextStep({ version: VERSION, root, next, budgetLine: "" }));
       }
       process.exit(0);
       break;
@@ -709,11 +868,12 @@ async function main() {
     case "task": {
       const subCommand = args[1] || "create";
       if (subCommand === "create") {
-        const { values } = parseArgs({
+        const { values, positionals } = parseArgs({
           args: args.slice(2),
           options: {
             title: { type: "string", short: "t" },
             prompt: { type: "string", short: "p" },
+            "prompt-file": { type: "string", short: "f" },
             role: { type: "string", short: "r" },
             tier: { type: "string" },
             template: { type: "string" },
@@ -732,7 +892,7 @@ async function main() {
         const { runTaskCreateWizard } = await import("../src/wizard-task.mjs");
         const res = await runTaskCreateWizard(root, {
           title: values.title,
-          prompt: values.prompt,
+          prompt: resolvePromptInput(values, positionals),
           role: values.role,
           tier: values.tier,
           template: values.template,
@@ -806,6 +966,12 @@ async function main() {
           args: args.slice(2),
           options: {
             fix: { type: "boolean", short: "f" },
+            prompt: { type: "string", short: "p" },
+            // No short form here: `-f` is already --fix on this subcommand, and
+            // silently meaning two different things would be worse than one
+            // command having a flag short of full parity. `--file` predates
+            // `--prompt-file` and stays as an alias.
+            "prompt-file": { type: "string" },
             file: { type: "string" },
             dir: { type: "string", short: "d" },
             web: { type: "boolean", short: "w" },
@@ -818,16 +984,7 @@ async function main() {
 
         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);
-          }
-        }
+        const promptText = resolvePromptInput(values, positionals);
 
         if (values.fix) {
           const opt = optimizeTaskPrompt(promptText, { rootDir: targetDir, verifyCmd: values["verify-cmd"], web: values.web });
@@ -910,6 +1067,12 @@ async function main() {
           intent: { type: "string", short: "i" },
           handover: { type: "boolean", default: true },
           json: { type: "boolean", short: "j" },
+          // Documented in the README as `rollback [sessionId | --latest]` but
+          // never registered, so the documented spelling died in parseArgs
+          // before restoreCheckpoint — which has always accepted it — was
+          // reached. Restoring the newest checkpoint is also the no-argument
+          // default, so the flag is explicit-intent sugar rather than a mode.
+          latest: { type: "boolean" },
         },
         allowPositionals: true,
       });
@@ -1728,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/bin/init.js

@@ -117,53 +117,17 @@ if (detected.testCmd || detected.buildCmd) {
   console.log(`   - Build Command: ${detected.buildCmd || "(none)"}`);
 }
 
-// 2. Scaffold AGENTS.md / .agent/jules-protocol.md
-const agentsFile = path.join(targetDir, "AGENTS.md");
-const julesRulesSource = path.join(kitRoot, "JULES_RULES_TEMPLATE.md");
-
-if (!fs.existsSync(agentsFile) || isForce) {
-  if (fs.existsSync(julesRulesSource)) {
-    fs.copyFileSync(julesRulesSource, agentsFile);
-    console.log("✅ Created: AGENTS.md");
-  }
-} else {
-  const existingContent = fs.readFileSync(agentsFile, "utf-8");
-  if (!existingContent.includes("<MCP_DIRECTIVE>")) {
-    if (fs.existsSync(julesRulesSource)) {
-      const templateContent = fs.readFileSync(julesRulesSource, "utf-8");
-      fs.appendFileSync(agentsFile, `\n\n---\n\n${templateContent}`, "utf-8");
-      console.log("✅ Appended Google Jules directives to existing AGENTS.md");
-    }
-  } else {
-    console.log("ℹ️ AGENTS.md already contains Jules directives (skipped overwrite).");
-  }
+// 2-3. Scaffold AGENTS.md, .agent/ structure, role prompts, rules and workflows.
+// Shared with `agentctl init` so the two entry points cannot scaffold different
+// repositories — which is exactly what they used to do, with the README's
+// quickstart pointing at the one that scaffolded less.
+const { scaffoldRepoAssets } = await import("../src/scaffold.mjs");
+const scaffolded = scaffoldRepoAssets(targetDir, { force: isForce });
+for (const item of scaffolded.created) {
+  console.log(`✅ Created: ${item}`);
 }
 
-// 3. Scaffold .agent/ structure
 const agentDir = path.join(targetDir, ".agent");
-const rulesDir = path.join(agentDir, "rules");
-const queueDir = path.join(agentDir, "jules-queue");
-const completedQueueDir = path.join(queueDir, "completed");
-const workflowsDir = path.join(agentDir, "workflows");
-const promptsDir = path.join(agentDir, "prompts");
-
-[agentDir, rulesDir, queueDir, completedQueueDir, workflowsDir, promptsDir].forEach((d) => {
-  if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
-});
-
-// Scaffold .agent/prompts files
-const sourcePromptsDir = path.join(kitRoot, ".agent/prompts");
-if (fs.existsSync(sourcePromptsDir)) {
-  const promptFiles = fs.readdirSync(sourcePromptsDir);
-  promptFiles.forEach((file) => {
-    const srcPrompt = path.join(sourcePromptsDir, file);
-    const destPrompt = path.join(promptsDir, file);
-    if (!fs.existsSync(destPrompt) || isForce) {
-      fs.copyFileSync(srcPrompt, destPrompt);
-    }
-  });
-  console.log("✅ Created: .agent/prompts presets (Overseer, Bolt, Sentinel, Janitor, Task_Template)");
-}
 
 // Scaffold .agent/jules.yml
 const yamlConfigPath = path.join(agentDir, "jules.yml");
@@ -178,22 +142,6 @@ forbidden_paths: [".github/**", "**/.env*", "**/*.pem", "**/lock-manager*"]
   console.log("✅ Created: .agent/jules.yml");
 }
 
-// Scaffold .agent/rules/dynamic-guardrails.json
-const dgcSource = path.join(kitRoot, ".agent/rules/dynamic-guardrails.json");
-const dgcTarget = path.join(rulesDir, "dynamic-guardrails.json");
-if ((!fs.existsSync(dgcTarget) || isForce) && fs.existsSync(dgcSource)) {
-  fs.copyFileSync(dgcSource, dgcTarget);
-  console.log("✅ Created: .agent/rules/dynamic-guardrails.json");
-}
-
-// Scaffold .agent/workflows/jules-review.md
-const reviewSource = path.join(kitRoot, ".agent/workflows/jules-review.md");
-const reviewTarget = path.join(workflowsDir, "jules-review.md");
-if ((!fs.existsSync(reviewTarget) || isForce) && fs.existsSync(reviewSource)) {
-  fs.copyFileSync(reviewSource, reviewTarget);
-  console.log("✅ Created: .agent/workflows/jules-review.md");
-}
-
 // Scaffold .github/workflows/jules-audit.yml
 const githubWorkflowsDir = path.join(targetDir, ".github/workflows");
 const auditWfSource = path.join(kitRoot, ".github/workflows/jules-audit.yml");
@@ -275,32 +223,10 @@ if (fs.existsSync(targetPkgPath) && targetDir !== kitRoot) {
   }
 }
 
-// 5b. Ensure target repository has .gitignore entries for sensitive and runtime state
-const targetGitignorePath = path.join(targetDir, ".gitignore");
-const requiredGitignoreEntries = [
-  ".env",
-  ".agent/history/",
-  ".agent/state/",
-  ".agent/jules-queue/.state/",
-  ".agent/jules-queue/failed/",
-  ".agent/jules-queue/.processing/",
-  ".agent/jules-queue/*.md",
-  "!.agent/jules-queue/README.md"
-];
-
-let gitignoreContent = fs.existsSync(targetGitignorePath)
-  ? fs.readFileSync(targetGitignorePath, "utf-8")
-  : "";
-
-const missingEntries = requiredGitignoreEntries.filter(
-  (entry) => !gitignoreContent.includes(entry)
-);
-
-if (missingEntries.length > 0) {
-  const prefix = gitignoreContent && !gitignoreContent.endsWith("\n") ? "\n" : "";
-  const addedBlock = `${prefix}# Jules Orchestrator Runtime State & Credentials\n${missingEntries.join("\n")}\n`;
-  fs.appendFileSync(targetGitignorePath, addedBlock, "utf-8");
-  console.log("✅ Added required security entries to .gitignore");
+// 5b. The .gitignore entries are written by scaffoldRepoAssets above, so the
+// two entry points cannot disagree about which runtime paths stay untracked.
+if (scaffolded.gitignore.length > 0) {
+  console.log(`✅ Added ${scaffolded.gitignore.length} runtime state entries to .gitignore`);
 }
 
 console.log("\n🎉 Google Jules Orchestration Kit successfully initialized!");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jules-orchestrator-kit",
-  "version": "0.41.0",
+  "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",