jules-orchestrator-kit 0.28.2 → 0.29.1

package/README.md

@@ -332,19 +332,21 @@ Native stdio server exposing task dispatch, gate verification, and risk auditing
 
 | Command | Usage | Description | Exit Codes |
 | :--- | :--- | :--- | :--- |
+| `init` | `agentctl init [--interactive] [--tier pro]` | Interactive onboarding wizard & stack oracle inspector generating `.agent/config.yml`. | `0` (Created) |
+| `task create` | `agentctl task create [--title <t>] [--prompt <p>]` | Interactively authors & scopes falsifiable task envelopes with secret scrubbing & preflight gate checks. | `0` (Queued), `1` (Unfalsifiable / Secret leak) |
 | `dispatch` | `agentctl dispatch --title <t> --prompt <p>` | Dispatches a single task to an AI agent in an isolated worktree. | `0` (Success), `1` (Arg error), `2` (429 Rate limit), `3` (Scope deny), `4` (OODA exhausted), `5` (Diff > 75KB), `6` (Secret leak) |
+| `scan` | `agentctl scan` | Scans codebase for TODO/FIXME annotations to seed task authoring. | `0` (Scanned) |
 | `review-repair`| `agentctl review-repair <pr-comments.json>`| Parses GitHub PR review comments and synthesizes actionable OODA repair tasks. | `0` (Parsed), `1` (Missing file) |
 | `dashboard` | `agentctl dashboard [port]` | Starts zero-dependency local HTTP telemetry and audit visualizer dashboard. | `0` (Running) |
-| `gate` / `audit`| `agentctl gate --base main --json` | Runs security, secret scanning, and verification gate against current branch. | `0` (Approved), `3` (Scope violation), `5` (Diff limit), `6` (Secret leak) |
+| `gate` / `audit`| `agentctl gate --mode working-tree --json` | Runs security, secret scanning, and verification gate against working tree or branch. | `0` (Approved), `3` (Scope violation), `5` (Diff limit), `6` (Secret leak) |
 | `bootstrap` | `agentctl bootstrap [--force] [--json]` | Inspects an untested repository and synthesizes `.agent/config.yml` with a zero-test verification oracle (`php -l`, `compileall`, `dotnet build`, `tsc`, `smoke`). | `0` (Bootstrapped / Existing) |
 | `queue` | `agentctl queue` | Consumes and executes pending markdown task envelopes in `.agent/queue/`. | `0` (Complete) |
 | `swarm` | `agentctl swarm` | Runs parallel multi-agent swarm across queued tasks with token-bucket concurrency. | `0` (Complete) |
 | `doctor` | `agentctl doctor` | Diagnostic inspect: displays detected stack, container wrapper, test command, and daily session budget. | `0` (Healthy) |
 | `lock` | `agentctl lock <acquire\|release\|status>`| Manages VFS mutex locks for multi-agent non-overlapping file ownership. | `0` (Locked/Released), `1` (Conflict) |
 | `clean` | `agentctl clean` | Prunes stale git worktrees, lockfiles, and temporary ledgers. | `0` (Clean) |
-| `init` | `agentctl init` | Scaffolds `.agent/` directory structure and default `.agent/config.yml`. | `0` (Created) |
 | `mcp` | `agentctl mcp` | Starts stdio Model Context Protocol (MCP) server for tool integration. | `0` / Stdio stream |
-| `version` | `agentctl version` | Outputs orchestrator kit semantic version (`v0.27.0`). | `0` |
+| `version` | `agentctl version` | Outputs orchestrator kit semantic version (`v0.29.0`). | `0` |
 
 <br/>
 
@@ -353,14 +355,15 @@ Native stdio server exposing task dispatch, gate verification, and risk auditing
 <br/>
 
 <a id="roadmap"></a>
-## 🗺️ v0.27+ Next-Gen Feature Roadmap
+## 🗺️ v0.29+ Feature Roadmap
 
 | Feature | Module / Command | Architectural Blueprint | Target Release |
 | :--- | :--- | :--- | :---: |
+| **Onboarding & Stack Oracle Wizard** | `agentctl init --interactive` (`src/wizard-init.mjs`) | Zero-dependency interactive CLI wizard auto-detecting verification oracles, quota tiers, and preset workflows. | **v0.29.0** *(Shipped)* |
+| **Guided Task Authoring Subsystem** | `agentctl task create` (`src/wizard-task.mjs`) | Guided task authoring with TODO candidate harvesting, Shannon entropy secret scrubbing, and guardrail footer synthesis. | **v0.29.0** *(Shipped)* |
 | **PR Review Auto-Remediation Loop** | `agentctl review-repair` (`src/review-repair.mjs`) | Ingests GitHub PR review comments (`CHANGES_REQUESTED`), extracts line/file context, and dispatches automated OODA repair turns until reviewer comments are resolved. | **v0.27.0** *(Shipped)* |
 | **Multi-Provider Failover Router** | `createFailoverProvider` (`src/provider.mjs`) | Ordered router (`["jules", "claude-code", "local-mcp"]`) that seamlessly falls back to secondary LLMs on HTTP 429 rate limits or 5xx service unavailability. | **v0.27.0** *(Shipped)* |
 | **Telemetry & Audit Web Dashboard**| `agentctl dashboard` (`src/dashboard.mjs`) | Zero-dependency local HTTP server displaying real-time DAG execution graphs, Wilson-Score flaky test ledgers, and SHA-256 telemetry chains. | **v0.27.0** *(Shipped)* |
-| **Cross-Language Contract Guard** | `hashCrossLanguageInterface` (`src/merge-blocks.mjs`)| Canonical SHA-256 schema hashing for OpenAPI/Protobuf specs across polyglot task dependencies in `DagExecutor`. | **v0.26.0** *(Shipped)* |
 
 <br/>
 
@@ -371,11 +374,10 @@ Native stdio server exposing task dispatch, gate verification, and risk auditing
 ## 📖 Recipes, Documentation & Prior Art
 
 - [**Google Jules Official Documentation**](https://jules.google) — Official platform overview and API specifications for Google Jules.
-- [**Google Labs Code Repositories**](https://github.com/google-labs-code) — Official Google Labs public GitHub organization (jules-action, jules-sdk).
+- [**Onboarding & Task Wizard Specification**](./docs/ONBOARDING_AND_TASK_WIZARD_SPEC.md) — Normative architecture specification for zero-dependency TUI, stack oracle, and guided task authoring.
 - [**Universal Polyglot Architecture & Zero-Test Specification**](./docs/UNIVERSAL_POLYGLOT_ARCHITECTURE.md) — Comprehensive technical report on boundary resolution, OODA math, and B2B workflows.
 - [**v0.27.0 Architectural Audit & Platform Evolution**](./docs/V0.27_ARCHITECTURAL_AUDIT_AND_EVOLUTION.md) — PR review remediation, failover router, and local dashboard specs.
 - [**Examples & Task Envelope Recipes**](./EXAMPLES.md) — Production YAML and Markdown task envelopes.
-- [**Adversarial Security Audit Phase 4 Report**](./docs/AUDIT_REPORT.md) — CWE-77, CWE-1321, and CWE-183 security hardening analysis.
 - [**Changelog**](./CHANGELOG.md) — Full release history and migration guides.
 
 <br/>

package/bin/agentctl.mjs

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 
 import { parseArgs } from "node:util";
-import { readFileSync, writeFileSync, existsSync, readdirSync } from "node:fs";
+import { readFileSync, existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { loadConfig, resolveRoot, detectStack, bootstrapZeroTestRepo } from "../src/config.mjs";
 import { gate, dispatch, run, isTaskFile } from "../src/engine.mjs";
-import { acquireLock, releaseLock, lockStatus, checkDailyBudget, getQueueDir, ensureDir } from "../src/state.mjs";
+import { acquireLock, releaseLock, lockStatus, checkDailyBudget, getQueueDir } from "../src/state.mjs";
 import { worktreePrune } from "../src/git.mjs";
 import { reapOrphanedIntents, reapStaleMutexDirs } from "../src/journal.mjs";
 
@@ -14,7 +14,7 @@ const command = args[0];
 
 function printHelp() {
   console.log(`
-🚀 agentctl v0.28.2 — Universal Agent Orchestrator & Safety Gatekeeper
+🚀 agentctl v0.29.1 — Universal Agent Orchestrator & Safety Gatekeeper
 
 Usage: agentctl <command> [options]
 
@@ -30,7 +30,8 @@ Commands:
   bootstrap             Bootstrap zero-test repository with verification oracle
   review-repair         Parse PR review comments and synthesize OODA repair tasks
   dashboard             Start local HTTP telemetry and audit dashboard
-  init                  Scaffold .agent/ directory and config.yml
+  init                  Scaffold .agent/ config and run onboarding wizard
+  task create           Interactively author and scope a Jules task envelope
   status                Display queue and system status summary
   scan                  Scan codebase for TODO/FIXME task candidates
   version               Output agentctl version
@@ -53,7 +54,7 @@ async function main() {
   }
 
   if (command === "version" || command === "--version" || command === "-v") {
-    console.log("agentctl v0.28.2");
+    console.log("agentctl v0.29.1");
     process.exit(0);
   }
 
@@ -264,7 +265,7 @@ async function main() {
     }
 
     case "doctor": {
-      console.log(`\n🔍 agentctl System Diagnostics (v0.28.2)`);
+      console.log(`\n🔍 agentctl System Diagnostics (v0.29.1)`);
       console.log(`--------------------------------------------------`);
       console.log(`  Project Root     : ${root}`);
       console.log(`  Config File      : ${config._file || "None (Using defaults)"}`);
@@ -326,34 +327,81 @@ async function main() {
     }
 
     case "init": {
-      const agentDir = join(root, ".agent");
-      ensureDir(agentDir);
-      const configPath = join(agentDir, "config.yml");
-      if (!existsSync(configPath)) {
-        writeFileSync(
-          configPath,
-          `version: 1
-provider: jules
-limits:
-  diff_kb: 75
-  daily_tasks: 300
-branch_prefix: agent/
-base_branch: main
-`,
-          "utf-8"
-        );
-        console.log(`✅ Created .agent/config.yml`);
+      const { values } = parseArgs({
+        args: args.slice(1),
+        options: {
+          interactive: { type: "boolean", short: "i" },
+          tier: { type: "string", short: "t" },
+          json: { type: "boolean", short: "j" },
+        },
+        allowPositionals: true,
+      });
+
+      const { runInitWizard } = await import("../src/wizard-init.mjs");
+      const res = await runInitWizard(root, {
+        interactive: values.interactive !== false,
+        tier: values.tier || "pro",
+      });
+
+      if (values.json) {
+        console.log(JSON.stringify(res, null, 2));
       } else {
-        console.log(`ℹ️ .agent/config.yml already exists.`);
+        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(", ")}`);
       }
       process.exit(0);
       break;
     }
 
+    case "task": {
+      const subCommand = args[1] || "create";
+      if (subCommand === "create") {
+        const { values } = parseArgs({
+          args: args.slice(2),
+          options: {
+            title: { type: "string", short: "t" },
+            prompt: { type: "string", short: "p" },
+            "verify-cmd": { type: "string", short: "v" },
+            "auto-pr": { type: "boolean" },
+            "require-plan-approval": { type: "boolean" },
+            repoless: { type: "boolean" },
+            json: { type: "boolean", short: "j" },
+          },
+          allowPositionals: true,
+        });
+
+        const { runTaskCreateWizard } = await import("../src/wizard-task.mjs");
+        const res = await runTaskCreateWizard(root, {
+          title: values.title,
+          prompt: values.prompt,
+          verifyCmd: values["verify-cmd"],
+          autoPr: values["auto-pr"],
+          requirePlanApproval: values["require-plan-approval"],
+          repoless: values.repoless,
+        });
+
+        if (values.json) {
+          console.log(JSON.stringify(res, null, 2));
+        } else {
+          console.log(`✅ Task synthesized & queued at ${res.taskFile}`);
+          console.log(`   Task ID  : ${res.plan.taskId}`);
+          console.log(`   Title    : ${res.plan.title}`);
+          console.log(`   Auto-PR  : ${res.plan.flags.autoPr}`);
+        }
+        process.exit(0);
+      } else {
+        console.error(`Unknown task subcommand '${subCommand}'. Supported: agentctl task create`);
+        process.exit(1);
+      }
+      break;
+    }
+
     case "status": {
       const queueDir = getQueueDir(root);
       const files = existsSync(queueDir) ? readdirSync(queueDir).filter((f) => isTaskFile(f, queueDir)) : [];
-      console.log(`\n📊 agentctl Status Summary (v0.28.2)`);
+      console.log(`\n📊 agentctl Status Summary (v0.29.1)`);
       console.log(`--------------------------------------------------`);
       console.log(`  Project Root     : ${root}`);
       console.log(`  Pending Tasks    : ${files.length}`);

package/index.mjs

@@ -1,5 +1,5 @@
 /**
- * Google Jules Orchestrator Kit - Node.js SDK (v0.28.2)
+ * Google Jules Orchestrator Kit - Node.js SDK (v0.29.1)
  *
  * Exposes core orchestrator functions for programmatically driving agent tasks,
  * security auditing, repo gating, and state operations.
@@ -73,3 +73,16 @@ export { getDynamicGuardrails, dispatchTask } from "./scripts/jules-dispatch.mjs
 export { classifyQueueFailure } from "./scripts/jules-queue-runner.mjs";
 export { extractPrUrls, auditSessions, buildSyncManifest, pushReservationManifest } from "./scripts/utils.mjs";
 
+// Native TUI Primitives
+export { isTTY, styleText, select, multiSelect, input, confirm, secretInput, spinner, ANSI } from "./src/tui.mjs";
+
+// Stack Oracle & Verification Probes
+export { detectStackOracles, runVerificationProbe } from "./src/wizard-oracle.mjs";
+
+// Onboarding & Presets Engine
+export { planInit, loadPresets, runInitWizard, TIER_PROFILES, BUILTIN_PRESETS } from "./src/wizard-init.mjs";
+
+// Guided Task Authoring Subsystem
+export { planTaskCreate, runTaskCreateWizard, GUARDRAIL_FOOTER } from "./src/wizard-task.mjs";
+
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jules-orchestrator-kit",
-  "version": "0.28.2",
+  "version": "0.29.1",
   "description": "Orchestration kit for running Google Jules autonomous agents.",
   "repository": {
     "type": "git",

package/src/dashboard.mjs

@@ -32,7 +32,7 @@ export function getDashboardHtml(root = process.cwd()) {
   </style>
 </head>
 <body>
-  <h1>🚀 jules-orchestrator-kit Dashboard (v0.28.2)</h1>
+  <h1>🚀 jules-orchestrator-kit Dashboard (v0.29.1)</h1>
   <div class="subtitle">Repository: <code>${root}</code></div>
 
   <div class="grid">
@@ -87,7 +87,7 @@ export function createDashboardServer({ root = process.cwd(), port: _port = 4100
 
     if (url.pathname === "/api/status") {
       res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
-      return res.end(JSON.stringify({ ok: true, version: "0.28.2", root, ts: new Date().toISOString() }));
+      return res.end(JSON.stringify({ ok: true, version: "0.29.1", root, ts: new Date().toISOString() }));
     }
 
     if (url.pathname === "/api/telemetry") {

package/src/engine.mjs

@@ -46,14 +46,8 @@ export function isTaskFile(fileName, queueDirOrContent = null) {
       }
       if (typeof content === "string") {
         const trimmed = content.trimStart();
-        if (trimmed.startsWith("---")) {
-          const endFm = trimmed.indexOf("\n---", 3);
-          if (endFm !== -1) {
-            const frontMatter = trimmed.slice(3, endFm);
-            if (/(?:taskId|envelopeId|baseRef|baseSha|task|title|id|version|capabilities|scope|verify):/i.test(frontMatter)) {
-              return true;
-            }
-          }
+        if (trimmed.includes("JULES_TASK_ENVELOPE") || trimmed.includes("# Task ID:") || trimmed.startsWith("---")) {
+          return true;
         }
       }
     } catch (_) {}

package/src/mcp.mjs

@@ -9,7 +9,7 @@ import { ProgressBus } from "./mcp-progress.mjs";
 
 export const MCP_SERVER_INFO = {
   name: "jules-orchestrator-kit",
-  version: "0.28.2",
+  version: "0.29.1",
 };
 
 export const MAX_MCP_FRAME_SIZE = 4 * 1024 * 1024; // 4 MB memory safety ceiling

package/src/security.mjs

@@ -13,7 +13,7 @@ export const HIGH_CONFIDENCE_PATTERNS = [
 
   /\bAKIA[0-9A-Z]{16}\b/g,
   /\bASIA[0-9A-Z]{16}\b/g,
-  /\baws_secret_access_key\s*=\s*['"]?[A-Za-z0-9\/+=]{40}['"]?/g,
+  /\baws_secret_access_key\s*=\s*['"]?[A-Za-z0-9\/+=]{40}['"]?/gi,
 
   /-----BEGIN (?:RSA|DSA|EC|OPENSSH|PRIVATE)(?:\s+PRIVATE)? KEY-----[\s\S]*?-----END (?:RSA|DSA|EC|OPENSSH|PRIVATE)(?:\s+PRIVATE)? KEY-----/g,
   /PuTTY-User-Key-File-[0-9]:[^\n]+/g,

package/src/tui.mjs

@@ -0,0 +1,414 @@
+import { createInterface } from "node:readline/promises";
+import { isatty } from "node:tty";
+
+// ANSI Styling & Escapes
+export const ANSI = {
+  reset: "\u001b[0m",
+  bold: "\u001b[1m",
+  dim: "\u001b[2m",
+  red: "\u001b[31m",
+  green: "\u001b[32m",
+  yellow: "\u001b[33m",
+  blue: "\u001b[34m",
+  cyan: "\u001b[36m",
+  white: "\u001b[37m",
+  bgCyan: "\u001b[46m",
+  bgBlue: "\u001b[44m",
+  hideCursor: "\u001b[?25l",
+  showCursor: "\u001b[?25h",
+  clearLine: "\u001b[2K\r",
+  cursorUp: (n = 1) => `\u001b[${n}A`,
+  cursorDown: (n = 1) => `\u001b[${n}B`,
+};
+
+/**
+ * Check if the given input stream is an interactive TTY terminal.
+ * @param {import("node:stream").Readable} [stream]
+ * @returns {boolean}
+ */
+export function isTTY(stream = process.stdin) {
+  return Boolean(stream && (stream.isTTY || isatty(stream.fd)));
+}
+
+/**
+ * Format string with ANSI styling if stream supports TTY.
+ * @param {string} text
+ * @param {string} style
+ * @returns {string}
+ */
+export function styleText(text, style) {
+  if (!style) return text;
+  return `${style}${text}${ANSI.reset}`;
+}
+
+export class WizardCancelledError extends Error {
+  constructor(message = "Wizard cancelled by user") {
+    super(message);
+    this.name = "WizardCancelledError";
+  }
+}
+
+/**
+ * Read keypress in raw mode from TTY input stream.
+ * @param {import("node:stream").Readable} stream
+ * @returns {AsyncGenerator<string, void, unknown>}
+ */
+async function* readKeypresses(stream = process.stdin) {
+  const wasRaw = stream.isRaw;
+  if (stream.setRawMode) {
+    stream.setRawMode(true);
+  }
+  stream.resume();
+  stream.setEncoding("utf-8");
+
+  try {
+    for await (const chunk of stream) {
+      const str = String(chunk);
+      if (str === "\u0003") {
+        // Ctrl+C SIGINT
+        process.stdout.write(ANSI.showCursor + "\n");
+        throw new WizardCancelledError("Wizard operation cancelled by user (SIGINT).");
+      }
+      yield str;
+    }
+  } finally {
+    if (stream.setRawMode) {
+      stream.setRawMode(Boolean(wasRaw));
+    }
+  }
+}
+
+/**
+ * Single-select interactive menu using TTY raw mode.
+ * @param {Array<{ label: string, value: any, description?: string }>} options
+ * @param {string} prompt
+ * @param {object} [opts]
+ * @returns {Promise<any>}
+ */
+export async function select(options, prompt, opts = {}) {
+  const stdin = opts.stdin || process.stdin;
+  const stdout = opts.stdout || process.stdout;
+
+  if (options.length === 0) {
+    throw new Error("select() requires at least one option.");
+  }
+
+  const defaultIdx = opts.defaultIdx ?? 0;
+  let currentIdx = Math.max(0, Math.min(options.length - 1, defaultIdx));
+
+  if (!isTTY(stdin)) {
+    // Non-TTY Headless fallback
+    if (opts.fallbackValue !== undefined) {
+      return opts.fallbackValue;
+    }
+    const val = options[currentIdx].value;
+    stdout.write(`[Headless Select] ${prompt}: Auto-selected default [${options[currentIdx].label}]\n`);
+    return val;
+  }
+
+  function render(isFinal = false) {
+    let out = `${ANSI.bold}${ANSI.cyan}?${ANSI.reset} ${ANSI.bold}${prompt}${ANSI.reset}\n`;
+    options.forEach((opt, idx) => {
+      const isSelected = idx === currentIdx;
+      const cursor = isSelected ? `${ANSI.cyan}❯${ANSI.reset}` : " ";
+      const label = isSelected ? `${ANSI.bold}${ANSI.cyan}${opt.label}${ANSI.reset}` : opt.label;
+      const desc = opt.description ? ` ${ANSI.dim}(${opt.description})${ANSI.reset}` : "";
+      out += `  ${cursor} ${label}${desc}\n`;
+    });
+    if (!isFinal) {
+      out += `${ANSI.dim}  (Use arrow keys or 1-${Math.min(9, options.length)} to select, Enter to confirm)${ANSI.reset}`;
+    }
+    return out;
+  }
+
+  stdout.write(ANSI.hideCursor);
+  let renderedLines = options.length + 2;
+  stdout.write(render());
+
+  try {
+    for await (const key of readKeypresses(stdin)) {
+      if (key === "\r" || key === "\n") {
+        // Confirm selection
+        stdout.write(ANSI.cursorUp(renderedLines) + ANSI.clearLine);
+        for (let i = 0; i < renderedLines; i++) {
+          stdout.write(ANSI.clearLine + ANSI.cursorDown(1));
+        }
+        stdout.write(ANSI.cursorUp(renderedLines));
+        stdout.write(`${ANSI.green}✔${ANSI.reset} ${ANSI.bold}${prompt}${ANSI.reset} ${ANSI.cyan}${options[currentIdx].label}${ANSI.reset}\n`);
+        return options[currentIdx].value;
+      }
+
+      let moved = false;
+      if (key === "\u001b[A" || key === "k") {
+        // Up
+        currentIdx = (currentIdx - 1 + options.length) % options.length;
+        moved = true;
+      } else if (key === "\u001b[B" || key === "j") {
+        // Down
+        currentIdx = (currentIdx + 1) % options.length;
+        moved = true;
+      } else if (/^[1-9]$/.test(key)) {
+        const num = parseInt(key, 10) - 1;
+        if (num < options.length) {
+          currentIdx = num;
+          moved = true;
+        }
+      }
+
+      if (moved) {
+        stdout.write(ANSI.cursorUp(renderedLines));
+        stdout.write(render());
+      }
+    }
+  } finally {
+    stdout.write(ANSI.showCursor);
+  }
+}
+
+/**
+ * Multi-select checkbox menu using TTY raw mode.
+ * @param {Array<{ label: string, value: any, checked?: boolean, description?: string }>} options
+ * @param {string} prompt
+ * @param {object} [opts]
+ * @returns {Promise<Array<any>>}
+ */
+export async function multiSelect(options, prompt, opts = {}) {
+  const stdin = opts.stdin || process.stdin;
+  const stdout = opts.stdout || process.stdout;
+
+  const selections = new Set();
+  options.forEach((opt, idx) => {
+    if (opt.checked) selections.add(idx);
+  });
+
+  if (!isTTY(stdin)) {
+    // Non-TTY Headless fallback
+    const selectedVals = options.filter((_, idx) => selections.has(idx)).map((o) => o.value);
+    stdout.write(`[Headless MultiSelect] ${prompt}: Auto-selected ${selectedVals.length} item(s)\n`);
+    return selectedVals;
+  }
+
+  let currentIdx = 0;
+  let renderedLines = options.length + 2;
+
+  function render() {
+    let out = `${ANSI.bold}${ANSI.cyan}?${ANSI.reset} ${ANSI.bold}${prompt}${ANSI.reset}\n`;
+    options.forEach((opt, idx) => {
+      const isHover = idx === currentIdx;
+      const isChecked = selections.has(idx);
+      const cursor = isHover ? `${ANSI.cyan}❯${ANSI.reset}` : " ";
+      const box = isChecked ? `${ANSI.green}[x]${ANSI.reset}` : `${ANSI.dim}[ ]${ANSI.reset}`;
+      const label = isHover ? `${ANSI.bold}${opt.label}${ANSI.reset}` : opt.label;
+      const desc = opt.description ? ` ${ANSI.dim}(${opt.description})${ANSI.reset}` : "";
+      out += `  ${cursor} ${box} ${label}${desc}\n`;
+    });
+    out += `${ANSI.dim}  (Space to toggle, 'a' select all, 'n' select none, Enter to confirm)${ANSI.reset}`;
+    return out;
+  }
+
+  stdout.write(ANSI.hideCursor);
+  stdout.write(render());
+
+  try {
+    for await (const key of readKeypresses(stdin)) {
+      if (key === "\r" || key === "\n") {
+        const resultVals = options.filter((_, idx) => selections.has(idx)).map((o) => o.value);
+        stdout.write(ANSI.cursorUp(renderedLines));
+        for (let i = 0; i < renderedLines; i++) {
+          stdout.write(ANSI.clearLine + ANSI.cursorDown(1));
+        }
+        stdout.write(ANSI.cursorUp(renderedLines));
+        stdout.write(`${ANSI.green}✔${ANSI.reset} ${ANSI.bold}${prompt}${ANSI.reset} ${ANSI.cyan}${resultVals.length} selected${ANSI.reset}\n`);
+        return resultVals;
+      }
+
+      let redraw = false;
+      if (key === "\u001b[A" || key === "k") {
+        currentIdx = (currentIdx - 1 + options.length) % options.length;
+        redraw = true;
+      } else if (key === "\u001b[B" || key === "j") {
+        currentIdx = (currentIdx + 1) % options.length;
+        redraw = true;
+      } else if (key === " ") {
+        if (selections.has(currentIdx)) {
+          selections.delete(currentIdx);
+        } else {
+          selections.add(currentIdx);
+        }
+        redraw = true;
+      } else if (key === "a" || key === "A") {
+        options.forEach((_, idx) => selections.add(idx));
+        redraw = true;
+      } else if (key === "n" || key === "N") {
+        selections.clear();
+        redraw = true;
+      }
+
+      if (redraw) {
+        stdout.write(ANSI.cursorUp(renderedLines));
+        stdout.write(render());
+      }
+    }
+  } finally {
+    stdout.write(ANSI.showCursor);
+  }
+}
+
+/**
+ * Text input prompt with validation.
+ * @param {string} prompt
+ * @param {object} [opts]
+ * @returns {Promise<string>}
+ */
+export async function input(prompt, opts = {}) {
+  const stdin = opts.stdin || process.stdin;
+  const stdout = opts.stdout || process.stdout;
+  const defaultValue = opts.defaultValue ?? "";
+  const validate = opts.validate || (() => true);
+
+  if (!isTTY(stdin)) {
+    if (opts.fallbackValue !== undefined) {
+      return opts.fallbackValue;
+    }
+    stdout.write(`[Headless Input] ${prompt}: Auto-selected default [${defaultValue}]\n`);
+    return defaultValue;
+  }
+
+  const rl = createInterface({ input: stdin, output: stdout });
+
+  try {
+    while (true) {
+      const defaultHint = defaultValue ? ` ${ANSI.dim}(${defaultValue})${ANSI.reset}` : "";
+      const query = `${ANSI.bold}${ANSI.cyan}?${ANSI.reset} ${ANSI.bold}${prompt}${defaultHint}: `;
+      const rawAns = await rl.question(query);
+      const ans = rawAns.trim() || defaultValue;
+
+      const validRes = await validate(ans);
+      if (validRes === true) {
+        return ans;
+      }
+
+      const errMsg = typeof validRes === "string" ? validRes : "Invalid input";
+      stdout.write(`${ANSI.red}✖ ${errMsg}${ANSI.reset}\n`);
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+/**
+ * Confirmation prompt (Y/n).
+ * @param {string} prompt
+ * @param {boolean} [defaultVal=true]
+ * @param {object} [opts]
+ * @returns {Promise<boolean>}
+ */
+export async function confirm(prompt, defaultVal = true, opts = {}) {
+  const stdin = opts.stdin || process.stdin;
+  const stdout = opts.stdout || process.stdout;
+
+  if (!isTTY(stdin)) {
+    const val = opts.fallbackValue ?? defaultVal;
+    stdout.write(`[Headless Confirm] ${prompt}: Auto-selected [${val ? "Yes" : "No"}]\n`);
+    return val;
+  }
+
+  const hint = defaultVal ? "[Y/n]" : "[y/N]";
+  const ans = await input(`${prompt} ${ANSI.dim}${hint}${ANSI.reset}`, {
+    defaultValue: defaultVal ? "y" : "n",
+    stdin,
+    stdout,
+  });
+
+  return /^y(es)?$/i.test(ans.trim());
+}
+
+/**
+ * Password / secret input prompt.
+ * @param {string} prompt
+ * @param {object} [opts]
+ * @returns {Promise<string>}
+ */
+export async function secretInput(prompt, opts = {}) {
+  const stdin = opts.stdin || process.stdin;
+  const stdout = opts.stdout || process.stdout;
+
+  if (!isTTY(stdin)) {
+    return opts.fallbackValue || "";
+  }
+
+  stdout.write(`${ANSI.bold}${ANSI.cyan}?${ANSI.reset} ${ANSI.bold}${prompt}:${ANSI.reset} `);
+  stdout.write(ANSI.hideCursor);
+
+  let inputStr = "";
+  try {
+    for await (const key of readKeypresses(stdin)) {
+      if (key === "\r" || key === "\n") {
+        stdout.write("\n");
+        return inputStr;
+      }
+      if (key === "\u007f" || key === "\b") {
+        // Backspace
+        if (inputStr.length > 0) {
+          inputStr = inputStr.slice(0, -1);
+          stdout.write("\b \b");
+        }
+      } else if (key.length === 1 && key >= " ") {
+        inputStr += key;
+        stdout.write("*");
+      }
+    }
+  } finally {
+    stdout.write(ANSI.showCursor);
+  }
+  return inputStr;
+}
+
+/**
+ * Terminal activity spinner indicator.
+ * @param {string} label
+ * @param {object} [opts]
+ * @returns {{ stop: (msg?: string) => void, fail: (msg?: string) => void }}
+ */
+export function spinner(label, opts = {}) {
+  const stdout = opts.stdout || process.stdout;
+  const frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+  let frameIdx = 0;
+  let timer = null;
+
+  if (isTTY(stdout)) {
+    stdout.write(ANSI.hideCursor);
+    stdout.write(`${ANSI.cyan}${frames[0]}${ANSI.reset} ${label}`);
+
+    timer = setInterval(() => {
+      frameIdx = (frameIdx + 1) % frames.length;
+      stdout.write(ANSI.clearLine);
+      stdout.write(`${ANSI.cyan}${frames[frameIdx]}${ANSI.reset} ${label}`);
+    }, 80);
+  } else {
+    stdout.write(`[Starting] ${label}...\n`);
+  }
+
+  return {
+    stop(successMsg = `${label} complete`) {
+      if (timer) clearInterval(timer);
+      if (isTTY(stdout)) {
+        stdout.write(ANSI.clearLine);
+        stdout.write(`${ANSI.green}✔${ANSI.reset} ${successMsg}\n`);
+        stdout.write(ANSI.showCursor);
+      } else {
+        stdout.write(`[Completed] ${successMsg}\n`);
+      }
+    },
+    fail(errorMsg = `${label} failed`) {
+      if (timer) clearInterval(timer);
+      if (isTTY(stdout)) {
+        stdout.write(ANSI.clearLine);
+        stdout.write(`${ANSI.red}✖${ANSI.reset} ${errorMsg}\n`);
+        stdout.write(ANSI.showCursor);
+      } else {
+        stdout.write(`[Failed] ${errorMsg}\n`);
+      }
+    },
+  };
+}

package/src/wizard-init.mjs

@@ -0,0 +1,273 @@
+import { existsSync, readFileSync, writeFileSync, openSync, fsyncSync, closeSync, renameSync, mkdirSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { parseYaml } from "./config.mjs";
+import { detectStackOracles, runVerificationProbe } from "./wizard-oracle.mjs";
+import { select, multiSelect, input, confirm, spinner, isTTY } from "./tui.mjs";
+
+/**
+ * Write a file atomically using a temporary file and atomic rename.
+ * @param {string} filePath
+ * @param {string} content
+ */
+function writeAtomic(filePath, content) {
+  const tmpPath = `${filePath}.tmp.${Date.now()}.${Math.random().toString(36).slice(2)}`;
+  const fd = openSync(tmpPath, "w");
+  try {
+    writeFileSync(fd, content, "utf-8");
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+  renameSync(tmpPath, filePath);
+}
+
+export const TIER_PROFILES = {
+  free: {
+    concurrency: 1,
+    daily_tasks: 30,
+    stagger_ms: 3000,
+    diff_kb: 50,
+  },
+  pro: {
+    concurrency: 3,
+    daily_tasks: 300,
+    stagger_ms: 1500,
+    diff_kb: 75,
+  },
+  enterprise: {
+    concurrency: 10,
+    daily_tasks: 1000,
+    stagger_ms: 500,
+    diff_kb: 100,
+  },
+};
+
+export const BUILTIN_PRESETS = [
+  {
+    id: "nightly-security-audit",
+    title: "Nightly Security & Vulnerability Audit",
+    description: "Scans codebase for hardcoded secrets, TODO annotations, and outdated dependencies.",
+    cron: "0 2 * * *",
+  },
+  {
+    id: "flaky-test-quarantine",
+    title: "Statistical Flaky Test Quarantine",
+    description: "Monitors test execution stability via Wilson score interval and isolates flaky tests.",
+    cron: "*/30 * * * *",
+  },
+  {
+    id: "multi-agent-refactor-swarm",
+    title: "Multi-Agent Parallel Refactor Swarm",
+    description: "Splits refactoring tasks across isolated workspace file boundaries.",
+    cron: "manual",
+  },
+  {
+    id: "doc-sync-sentinel",
+    title: "AGENTS.md & API Doc Sync Sentinel",
+    description: "Validates documentation integrity against actual exported symbol signatures.",
+    cron: "0 9 * * 1",
+  },
+];
+
+/**
+ * Generate a deterministic onboarding plan for repository configuration.
+ * @param {string} [root=process.cwd()]
+ * @param {object} [options]
+ * @returns {{
+ *   stack: string,
+ *   tier: string,
+ *   verify: { test: string, build: string, lint: string, typecheck: string },
+ *   limits: { concurrency: number, daily_tasks: number, stagger_ms: number, diff_kb: number },
+ *   presets: Array<string>,
+ *   configYaml: string,
+ *   julesYaml: string
+ * }}
+ */
+export function planInit(root = process.cwd(), options = {}) {
+  const oracle = detectStackOracles(root);
+  const tierName = options.tier || "pro";
+  const limits = TIER_PROFILES[tierName] || TIER_PROFILES.pro;
+
+  // Preserve existing config if present
+  let existingConfig = {};
+  const existingConfigPath = join(root, ".agent", "config.yml");
+  if (existsSync(existingConfigPath)) {
+    try {
+      existingConfig = parseYaml(readFileSync(existingConfigPath, "utf-8")) || {};
+    } catch (_) {}
+  }
+
+  const verify = {
+    test: options.testCmd || existingConfig.verify?.test || oracle.candidates.testCmd || "",
+    build: options.buildCmd || existingConfig.verify?.build || oracle.candidates.buildCmd || "",
+    lint: options.lintCmd || existingConfig.verify?.lint || oracle.candidates.lintCmd || "",
+    typecheck: options.typecheckCmd || existingConfig.verify?.typecheck || oracle.candidates.typecheckCmd || "",
+  };
+
+  const selectedPresets = options.presets || existingConfig.presets || ["nightly-security-audit", "flaky-test-quarantine"];
+
+  const configYaml = `# Google Jules Orchestrator Kit Config (v0.29.0)
+version: 1
+provider: ${existingConfig.provider || "jules"}
+tier: ${tierName}
+base_branch: ${options.baseBranch || existingConfig.base_branch || "main"}
+branch_prefix: ${existingConfig.branch_prefix || "agent/"}
+
+limits:
+  concurrency: ${limits.concurrency}
+  daily_tasks: ${limits.daily_tasks}
+  stagger_ms: ${limits.stagger_ms}
+  diff_kb: ${limits.diff_kb}
+
+verify:
+  test: "${verify.test}"
+  build: "${verify.build}"
+  lint: "${verify.lint}"
+  typecheck: "${verify.typecheck}"
+
+presets:
+${selectedPresets.map((p) => `  - ${p}`).join("\n")}
+`;
+
+  const julesYaml = `# Google Jules Agent Compatibility Manifest
+version: 1
+test_cmd: "${verify.test}"
+build_cmd: "${verify.build}"
+`;
+
+  return {
+    stack: oracle.stack,
+    tier: tierName,
+    verify,
+    limits,
+    presets: selectedPresets,
+    configYaml,
+    julesYaml,
+  };
+}
+
+/**
+ * Load declarative presets from .agent/presets/*.yml or fallback to built-ins.
+ * @param {string} [root=process.cwd()]
+ * @returns {Array<{ id: string, title: string, description: string, cron: string }>}
+ */
+export function loadPresets(root = process.cwd()) {
+  const presetsDir = join(root, ".agent", "presets");
+  const presets = [...BUILTIN_PRESETS];
+
+  if (existsSync(presetsDir)) {
+    try {
+      const files = readdirSync(presetsDir).filter((f) => f.endsWith(".yml") || f.endsWith(".yaml"));
+      files.forEach((f) => {
+        try {
+          const content = readFileSync(join(presetsDir, f), "utf-8");
+          const parsed = parseYaml(content);
+          if (parsed && parsed.id && parsed.title) {
+            presets.push({
+              id: parsed.id,
+              title: parsed.title,
+              description: parsed.description || "",
+              cron: parsed.cron || "manual",
+            });
+          }
+        } catch (_) {}
+      });
+    } catch (_) {}
+  }
+
+  return presets;
+}
+
+/**
+ * Run interactive or headless onboarding wizard.
+ * @param {string} [root=process.cwd()]
+ * @param {object} [options]
+ * @returns {Promise<{ ok: boolean, configPath: string, plan: object }>}
+ */
+export async function runInitWizard(root = process.cwd(), options = {}) {
+  const interactive = options.interactive !== false && isTTY(options.stdin || process.stdin);
+
+  if (!interactive && !options.allowDefaults && !options.tier) {
+    throw new Error("Non-interactive init requires explicit options or allowDefaults: true");
+  }
+
+  let selectedTier = options.tier || "pro";
+  let testCmd = options.testCmd;
+  let buildCmd = options.buildCmd;
+  let selectedPresets = options.presets;
+
+  if (interactive) {
+    const oracle = detectStackOracles(root);
+    const sp = spinner("Inspecting repository stack and verification oracles", options);
+    await new Promise((resolve) => setTimeout(resolve, 300));
+    sp.stop(`Detected Stack: ${oracle.stack}`);
+
+    selectedTier = await select(
+      [
+        { label: "Pro Tier (Recommended)", value: "pro", description: "3 parallel workers, 300 daily tasks, 75 KB diff limit" },
+        { label: "Free / Individual Tier", value: "free", description: "1 worker, 30 daily tasks, 50 KB diff limit" },
+        { label: "Custom Enterprise", value: "enterprise", description: "10 workers, 1000 daily tasks, 100 KB diff limit" },
+      ],
+      "Select Jules Orchestrator Usage Tier",
+      options
+    );
+
+    testCmd = await input("Verification Test Command", {
+      defaultValue: oracle.candidates.testCmd || "npm test",
+      stdin: options.stdin,
+      stdout: options.stdout,
+    });
+
+    buildCmd = await input("Verification Build Command", {
+      defaultValue: oracle.candidates.buildCmd || "",
+      stdin: options.stdin,
+      stdout: options.stdout,
+    });
+
+    const presetOptions = BUILTIN_PRESETS.map((p) => ({
+      label: p.title,
+      value: p.id,
+      checked: true,
+      description: p.description,
+    }));
+
+    selectedPresets = await multiSelect(presetOptions, "Select Autonomous Workflows to Enable", options);
+
+    const shouldProbe = await confirm("Run verification probe on test command before saving?", true, options);
+    if (shouldProbe && testCmd) {
+      const probeSp = spinner(`Probing oracle: ${testCmd}`, options);
+      const probeRes = await runVerificationProbe(testCmd, root);
+      if (probeRes.ok) {
+        probeSp.stop(`Oracle verified successfully (${probeRes.durationMs}ms)`);
+      } else {
+        probeSp.fail(`Oracle verification probe failed (Exit ${probeRes.code})`);
+      }
+    }
+  }
+
+  const plan = planInit(root, {
+    tier: selectedTier,
+    testCmd,
+    buildCmd,
+    presets: selectedPresets,
+    ...options,
+  });
+
+  // Atomic write plan
+  const agentDir = join(root, ".agent");
+  if (!existsSync(agentDir)) {
+    mkdirSync(agentDir, { recursive: true });
+  }
+
+  const configPath = join(agentDir, "config.yml");
+  const julesPath = join(agentDir, "jules.yml");
+
+  writeAtomic(configPath, plan.configYaml);
+  writeAtomic(julesPath, plan.julesYaml);
+
+  return {
+    ok: true,
+    configPath,
+    plan,
+  };
+}

package/src/wizard-oracle.mjs

@@ -0,0 +1,155 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { detectStack, parseYaml } from "./config.mjs";
+import { runCmd } from "./git.mjs";
+
+/**
+ * Inspect repository topology, workspace structure, and manifests to infer candidate verification oracles.
+ * @param {string} [root=process.cwd()]
+ * @returns {{
+ *   stack: string,
+ *   isMonorepo: boolean,
+ *   packages: Array<{ path: string, name: string, stack: string }>,
+ *   candidates: {
+ *     testCmd: string,
+ *     buildCmd: string,
+ *     lintCmd: string,
+ *     typecheckCmd: string
+ *   }
+ * }}
+ */
+export function detectStackOracles(root = process.cwd()) {
+  const detected = detectStack(root);
+  const stack = detected.stack || "node";
+
+  const candidates = {
+    testCmd: detected.testCmd || "",
+    buildCmd: detected.buildCmd || "",
+    lintCmd: "",
+    typecheckCmd: "",
+  };
+
+  const isMonorepo =
+    existsSync(join(root, "turbo.json")) ||
+    existsSync(join(root, "pnpm-workspace.yaml")) ||
+    existsSync(join(root, "lerna.json")) ||
+    existsSync(join(root, "nx.json"));
+
+  const packages = [];
+
+  // Check Node.json package.json scripts
+  const pkgPath = join(root, "package.json");
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+      const scripts = pkg.scripts || {};
+
+      if (scripts.test) candidates.testCmd = candidates.testCmd || "npm test";
+      if (scripts.build) candidates.buildCmd = candidates.buildCmd || "npm run build";
+      if (scripts.lint) candidates.lintCmd = "npm run lint";
+      if (scripts.typecheck || scripts["type-check"]) {
+        candidates.typecheckCmd = scripts.typecheck ? "npm run typecheck" : "npm run type-check";
+      } else if (existsSync(join(root, "tsconfig.json"))) {
+        candidates.typecheckCmd = "npx tsc --noEmit";
+      }
+    } catch (_) {}
+  }
+
+  // Check Cargo workspace
+  if (stack.includes("cargo") || existsSync(join(root, "Cargo.toml"))) {
+    const isCargoWs = existsSync(join(root, "Cargo.toml")) && readFileSync(join(root, "Cargo.toml"), "utf-8").includes("[workspace]");
+    const flag = isCargoWs ? " --workspace" : "";
+    candidates.testCmd = `cargo test${flag}`;
+    candidates.buildCmd = `cargo build${flag}`;
+    candidates.lintCmd = `cargo clippy${flag} -- -D warnings`;
+    candidates.typecheckCmd = `cargo check${flag}`;
+  }
+
+  // Check Go module
+  if (stack.includes("go") || existsSync(join(root, "go.mod"))) {
+    candidates.testCmd = candidates.testCmd || "go test ./...";
+    candidates.buildCmd = candidates.buildCmd || "go build ./...";
+    candidates.lintCmd = candidates.lintCmd || "golangci-lint run";
+    candidates.typecheckCmd = candidates.typecheckCmd || "go vet ./...";
+  }
+
+  // Check Python
+  if (stack.includes("pytest") || existsSync(join(root, "pyproject.toml")) || existsSync(join(root, "requirements.txt"))) {
+    candidates.testCmd = candidates.testCmd || "pytest";
+    candidates.buildCmd = candidates.buildCmd || "";
+    candidates.lintCmd = candidates.lintCmd || "flake8 .";
+    candidates.typecheckCmd = candidates.typecheckCmd || "mypy .";
+  }
+
+  // Discover subpackages if monorepo
+  if (isMonorepo) {
+    if (existsSync(join(root, "pnpm-workspace.yaml"))) {
+      try {
+        const parsed = parseYaml(readFileSync(join(root, "pnpm-workspace.yaml"), "utf-8"));
+        const globs = parsed?.packages || ["packages/*"];
+        globs.forEach((pattern) => {
+          const dirBase = pattern.replace(/\/\*$/, "");
+          const fullDir = join(root, dirBase);
+          if (existsSync(fullDir)) {
+            const children = readdirSync(fullDir);
+            children.forEach((child) => {
+              const childPath = join(fullDir, child);
+              if (existsSync(join(childPath, "package.json"))) {
+                packages.push({
+                  path: join(dirBase, child),
+                  name: child,
+                  stack: "node",
+                });
+              }
+            });
+          }
+        });
+      } catch (_) {}
+    }
+  }
+
+  return {
+    stack,
+    isMonorepo,
+    packages,
+    candidates,
+  };
+}
+
+/**
+ * Execute a candidate verification command to prove oracle validity.
+ * @param {string} cmd
+ * @param {string} [cwd=process.cwd()]
+ * @param {object} [options]
+ * @returns {Promise<{ ok: boolean, code: number, stdout: string, stderr: string, durationMs: number }>}
+ */
+export async function runVerificationProbe(cmd, cwd = process.cwd(), options = {}) {
+  const start = Date.now();
+  const timeoutMs = options.timeoutMs || 30_000;
+
+  if (!cmd || !cmd.trim()) {
+    return { ok: true, code: 0, stdout: "", stderr: "Empty oracle command (skipped)", durationMs: 0 };
+  }
+
+  try {
+    const res = runCmd(cmd, { cwd, timeout: timeoutMs });
+    const durationMs = Date.now() - start;
+    const ok = res.status === 0;
+    return {
+      ok,
+      code: res.status ?? (ok ? 0 : 1),
+      stdout: res.stdout || "",
+      stderr: res.stderr || "",
+      durationMs,
+    };
+  } catch (err) {
+    const durationMs = Date.now() - start;
+    return {
+      ok: false,
+      code: 1,
+      stdout: "",
+      stderr: err.message,
+      durationMs,
+    };
+  }
+}

package/src/wizard-task.mjs

@@ -0,0 +1,223 @@
+import { writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { loadConfig } from "./config.mjs";
+import { gate } from "./engine.mjs";
+import { scanDiff, shannonEntropy } from "./security.mjs";
+import { getQueueDir } from "./state.mjs";
+import { scanCodebaseForTodos } from "../scripts/jules-scan-todos.mjs";
+import { select, input, confirm, spinner, isTTY } from "./tui.mjs";
+
+export const GUARDRAIL_FOOTER = `
+---
+HARD CONSTRAINTS:
+- Do NOT modify package.json, pnpm-lock.yaml, tsconfig.json, or .github/ files.
+- Diff Payload Governor: Keep total diff payload under 75 KB (\`git diff | wc -c\`).
+- Falsifiable & Evidence-Based: Attach full terminal verification output to PR. Never weaken assertions or delete failing tests to force a pass.
+- Read-Before-Write: Inspect existing symbol signatures, definitions, and call sites before making edits.
+- BEFORE opening the PR: Run \`git fetch origin main && git rebase origin/main\`, then re-verify.
+`;
+
+const TRIVIAL_ORACLES = new Set(["true", "echo", ":", "false", "exit 0", "exit 1", "echo ok"]);
+
+/**
+ * Pure planning core for task creation & envelope synthesis.
+ * @param {string} root
+ * @param {object} inputObj
+ * @returns {{
+ *   ok: boolean,
+ *   taskId: string,
+ *   title: string,
+ *   prompt: string,
+ *   fullPrompt: string,
+ *   verifyCmd: string,
+ *   flags: { autoPr: boolean, requirePlanApproval: boolean, repoless: boolean, startingBranch: string },
+ *   secretFindings: Array<any>,
+ *   taskFileContent: string
+ * }}
+ */
+export function planTaskCreate(root = process.cwd(), inputObj = {}) {
+  const config = loadConfig(root);
+
+  const title = inputObj.title || "Agent Task";
+  const rawPrompt = inputObj.prompt || "";
+  const verifyCmd = (inputObj.verifyCmd || config.verify.test || config.verify.build || "").trim();
+
+  // 1. Falsifiability check
+  if (!rawPrompt.trim()) {
+    throw new Error("Task prompt cannot be empty.");
+  }
+  const cleanCmd = verifyCmd.toLowerCase().replace(/['"]/g, "").trim();
+  if ((!verifyCmd || TRIVIAL_ORACLES.has(cleanCmd)) && !inputObj.allowUnverifiable) {
+    throw new Error(
+      "Unfalsifiable Task Rejected: Task must include a non-trivial verification test/build command. Configure verify.test in .agent/config.yml or pass --verify-cmd."
+    );
+  }
+
+  // 2. Secret Scrubbing Preflight (multiline diff formatting)
+  const secretFindings = [];
+  const multilineDiff = rawPrompt.split("\n").map((line) => `+${line}`).join("\n");
+  const secretScan = scanDiff(multilineDiff);
+  if (!secretScan.ok) {
+    secretScan.findings.forEach((f) => secretFindings.push({ id: f.type || f.id || "SECRET_LEAK", ...f }));
+  }
+  if (shannonEntropy(rawPrompt) > 4.5 && !inputObj.allowHighEntropy) {
+    secretFindings.push({ id: "HIGH_ENTROPY_PROMPT", line: 1 });
+  }
+
+  // High-confidence secrets cannot be bypassed
+  const highConfidenceFindings = secretFindings.filter((f) => f.id !== "HIGH_ENTROPY_PROMPT");
+  if (highConfidenceFindings.length > 0) {
+    throw new Error(
+      `Pre-Dispatch Secret Leak Blocked: Prompt contains ${highConfidenceFindings.length} high-confidence secret finding(s). High-confidence credentials cannot be bypassed.`
+    );
+  }
+  if (secretFindings.length > 0 && !inputObj.allowSecrets) {
+    throw new Error(
+      `Pre-Dispatch Secret Leak Blocked: Prompt contains potential secrets or credentials (${secretFindings.length} finding(s)). Scrub keys before dispatching.`
+    );
+  }
+
+  // 3. Jules v1alpha Flags
+  const flags = {
+    autoPr: Boolean(inputObj.autoPr),
+    requirePlanApproval: Boolean(inputObj.requirePlanApproval),
+    repoless: Boolean(inputObj.repoless),
+    startingBranch: inputObj.startingBranch || config.baseBranch || "main",
+  };
+
+  // 4. Task ID Sanitization (Path Traversal Guard)
+  const rawId = inputObj.id || `TASK-${Date.now().toString(36).toUpperCase()}`;
+  const taskId = String(rawId).replace(/[^a-zA-Z0-9_-]/g, "_");
+
+  // 5. Prompt Envelope & Guardrail Footer Synthesis
+  const fullPrompt = `[TASK INSTRUCTIONS]
+${rawPrompt}
+
+[VERIFICATION ORACLE]
+Test/Verification Command: ${verifyCmd || "(None)"}
+
+${GUARDRAIL_FOOTER}`;
+
+  const envelopeMetadata = {
+    version: 1,
+    id: taskId,
+    title,
+    flags,
+    verifyCmd,
+  };
+
+  const taskFileContent = `<!-- JULES_TASK_ENVELOPE: ${JSON.stringify(envelopeMetadata)} -->
+# ${title}
+# Task ID: ${taskId}
+# Auto-PR: ${flags.autoPr} | Plan Approval: ${flags.requirePlanApproval} | Repoless: ${flags.repoless}
+
+${fullPrompt}
+`;
+
+  return {
+    ok: true,
+    taskId,
+    title,
+    prompt: rawPrompt,
+    fullPrompt,
+    verifyCmd,
+    flags,
+    secretFindings,
+    taskFileContent,
+  };
+}
+
+/**
+ * Run interactive or headless task creation wizard.
+ * @param {string} [root=process.cwd()]
+ * @param {object} [options]
+ * @returns {Promise<{ ok: boolean, taskFile: string, plan: object }>}
+ */
+export async function runTaskCreateWizard(root = process.cwd(), options = {}) {
+  const interactive = options.interactive !== false && isTTY(options.stdin || process.stdin);
+
+  let title = options.title;
+  let promptText = options.prompt;
+  let verifyCmd = options.verifyCmd;
+  let autoPr = options.autoPr;
+  let requirePlanApproval = options.requirePlanApproval;
+  let repoless = options.repoless;
+
+  if (interactive) {
+    const sp = spinner("Analyzing codebase task candidates & gate policy", options);
+    const todos = scanCodebaseForTodos(root);
+    await new Promise((resolve) => setTimeout(resolve, 200));
+    sp.stop(`Scanned ${todos.length} TODO/FIXME candidates`);
+
+    if (todos.length > 0 && !promptText) {
+      const useTodo = await confirm("Import prompt from scanned TODO candidate?", false, options);
+      if (useTodo) {
+        const selectedTodo = await select(
+          todos.slice(0, 10).map((t) => ({
+            label: `[${t.type}] ${t.text} (${t.file}:${t.line})`,
+            value: t,
+          })),
+          "Select TODO Candidate",
+          options
+        );
+        title = `Fix ${selectedTodo.type}: ${selectedTodo.text.slice(0, 40)}`;
+        promptText = `Resolve ${selectedTodo.type} in ${selectedTodo.file} at line ${selectedTodo.line}: ${selectedTodo.text}`;
+      }
+    }
+
+    title = await input("Task Title", {
+      defaultValue: title || "Refactor Component Module",
+      stdin: options.stdin,
+      stdout: options.stdout,
+    });
+
+    promptText = await input("Detailed Task Instructions", {
+      defaultValue: promptText || "Cleanly refactor module to improve readability and maintain full test coverage.",
+      stdin: options.stdin,
+      stdout: options.stdout,
+    });
+
+    autoPr = await confirm("Enable Automatic PR Creation (automationMode: AUTO_CREATE_PR)?", true, options);
+    requirePlanApproval = await confirm("Require Plan Approval Gate before execution?", false, options);
+    repoless = await confirm("Dispatch in Repoless mode (no repo source context)?", false, options);
+  }
+
+  const plan = planTaskCreate(root, {
+    title,
+    prompt: promptText,
+    verifyCmd,
+    autoPr,
+    requirePlanApproval,
+    repoless,
+    ...options,
+  });
+
+  // Perform Gate Preflight
+  const gateRes = await gate({ root, mode: "working-tree" });
+  if (!gateRes.ok && (gateRes.code === 3 || gateRes.code === 6) && !options.allowGateFailure) {
+    // Filter out uncommitted .agent/ config scope warnings if user initialized locally
+    const realViolations = gateRes.phases[0]?.violations?.filter((v) => !v.file.startsWith(".agent/")) || [];
+    if (realViolations.length > 0 || gateRes.code === 6) {
+      throw new Error(`Gate Preflight Rejected Task: Repository contains scope or secret violations (Exit ${gateRes.code}).`);
+    }
+  }
+
+  // Write Task File to canonical queue directory (getQueueDir)
+  const queueDir = getQueueDir(root);
+  if (!existsSync(queueDir)) {
+    mkdirSync(queueDir, { recursive: true });
+  }
+
+  const taskFile = resolve(queueDir, `${plan.taskId}.md`);
+  if (!taskFile.startsWith(resolve(queueDir))) {
+    throw new Error("Task ID path traversal blocked.");
+  }
+
+  writeFileSync(taskFile, plan.taskFileContent, "utf-8");
+
+  return {
+    ok: true,
+    taskFile,
+    plan,
+  };
+}