jules-orchestrator-kit 0.41.0 → 0.41.1

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 **706 unit tests across 85 suites passing in < 10.0s**.
 
 <br/>
 
@@ -146,18 +158,18 @@ To maximize PR merge rates, dispatch tasks according to deterministic boundaries
 
 | Command | Usage | Description | Exit Codes |
 | :--- | :--- | :--- | :--- |
-| `init` | `agentctl init [--interactive] [--tier pro]` | Interactive onboarding wizard & stack detector generating `.agent/config.yml`. | `0` (Created) |
+| `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) |
+| `gate` / `audit`| `agentctl gate --mode working-tree [--fix] [--json] [--json-report <path>]` | Runs security, secret scanning, and tiered verification gates (with declarative assertion support) against working tree or branch. Secret findings name the file and line; a failed verify stage reports its command, exit code and output. | `0` (Approved), `3` (Scope), `4` (Verify), `5` (Diff >75K), `6` (Secret), `8` (Flaky) |
 | `assert` | `agentctl assert [--dir <d>] [--file <f>] [--max-mb <n>] [--gzip] [--targets <g>] [--patterns <p>] [--json] [--json-report <p>]` | Runs declarative zero-dependency verification assertion primitives (`assert:dir-size`, `assert:file-size`, `assert:file-patterns`, `assert:exists`). | `0` (Passed), `1` (Assertion Failed) |
 | `rollback` | `agentctl rollback [sessionId \| --latest]` | Restores exact commit, uncommitted files, and cleans orphan task worktrees from pre-flight checkpoints. | `0` (Restored), `1` (Error) |
 | `resume` | `agentctl resume <sessionId> --response "<reply>"` | Streams engineer response back into active Google Jules warm session context window. | `0` (Resumed), `1` (Error) |
@@ -356,6 +368,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

@@ -76,6 +76,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 +94,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 +233,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 +255,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 +307,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}`);
@@ -274,13 +389,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 +426,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 +547,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 +570,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 +809,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 +825,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 +865,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 +889,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 +963,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 +981,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 +1064,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,
       });

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.41.1",
   "description": "Zero-dependency safety gatekeeper, test oracle generator, and multi-agent coordination protocol for Google Jules (jules) autonomous agents.",
   "repository": {
     "type": "git",

package/src/engine.mjs

@@ -357,7 +357,22 @@ export async function gate(opts = {}) {
           const runs = readVerifyRuns(root, stage.cmd);
           flakyVerdictResult = flakyVerdict(runs);
           if (flakyVerdictResult.verdict === "QUARANTINED") {
-            phases.push({ phase: "verify", ok: false, testResult, buildResult, flakyVerdict: flakyVerdictResult, executionRecords });
+            phases.push({
+              phase: "verify",
+              ok: false,
+              testResult,
+              buildResult,
+              failure: {
+                stageId: stage.id || "unit",
+                command: stage.cmd || null,
+                exitCode: res.status ?? null,
+                stdout: stdoutRedacted,
+                stderr: stderrRedacted,
+                diagnostics: [`Quarantined as flaky: ${flakyVerdictResult.reason || "alternating pass/fail across recent runs"}`],
+              },
+              flakyVerdict: flakyVerdictResult,
+              executionRecords,
+            });
             appendTelemetry(root, "gate_phase", { phase: "verify", ok: false, quarantined: true });
             appendTelemetry(root, "gate_finished", { ok: false, code: 8 });
             return { ok: false, code: 8, phases, flakyVerdict: flakyVerdictResult };
@@ -413,6 +428,31 @@ export async function gate(opts = {}) {
 
   const verifyOk = !failingCmd && !testTampered;
 
+  // What actually broke. Without this the verify phase reported `ok: false` and
+  // nothing else — not the stage, not the exit code, not a line of output — so
+  // the one gate failure the operator is expected to fix themselves was the
+  // only one that told them nothing about how. Both streams are already
+  // redacted at the point they were captured.
+  const verifyFailure = failingCmd
+    ? {
+        stageId: failingCmd.stageId || failingCmd.phase || "verify",
+        command: failingCmd.command || null,
+        exitCode: failingCmd.status ?? null,
+        stdout: failingCmd.stdout || "",
+        stderr: failingCmd.stderr || "",
+        diagnostics: failingCmd.diagnostics || [],
+      }
+    : testTampered
+      ? {
+          stageId: "test-integrity",
+          command: null,
+          exitCode: null,
+          stdout: "",
+          stderr: `Test files changed during the run (${preTestHash.slice(0, 12)} → ${postTestHash.slice(0, 12)}). evidence.strictTestLock treats a passing suite that the diff also rewrote as unproven.`,
+          diagnostics: [],
+        }
+      : null;
+
   // Generate & persist Evidence Manifest
   const evidenceManifest = generateEvidenceManifest(root, {
     taskId: opts.taskId,
@@ -449,6 +489,7 @@ export async function gate(opts = {}) {
     testResult,
     buildResult,
     serverResult,
+    failure: verifyFailure,
     executionRecords,
     testIntegrity: {
       preTestHash,
@@ -834,6 +875,15 @@ export async function dispatch(task = {}, opts = {}) {
     const roleObj = resolveRolePrompt(root, task.role);
     if (roleObj) {
       cleanPrompt = `${roleObj.content}\n\n${cleanPrompt}`.trim();
+    } else {
+      // A role reaching here comes from a task envelope or an internal
+      // synthesis rather than a typed flag, so the dispatch still proceeds with
+      // a generic agent — failing an automated heal swarm over a missing
+      // prompt file helps nobody. It must not proceed *silently* though: the
+      // caller asked for a specialist and is not getting one.
+      console.warn(
+        `⚠️  Role '${task.role}' has no prompt in .agent/prompts/ — dispatching without specialist context. Run 'agentctl init' to scaffold the shipped roles.`
+      );
     }
   }
 

package/src/git.mjs

@@ -27,6 +27,9 @@ export function runCmd(command, opts = {}) {
   let args = [];
   let useShell = false;
   let shellCmd = "";
+  // True when `args` came from splitting a whitespace-separated string, which
+  // means no element can itself contain whitespace. See the Windows note below.
+  let tokenized = false;
 
   if (Array.isArray(command)) {
     binary = command[0];
@@ -40,9 +43,25 @@ export function runCmd(command, opts = {}) {
       const tokens = trimmed.split(/\s+/).filter(Boolean);
       binary = tokens[0] || "";
       args = tokens.slice(1);
+      tokenized = true;
     }
   }
 
+  // Every package-manager entry point on Windows is a `.cmd` shim, and
+  // execFileSync cannot spawn one directly. `npm test` — the kit's own default
+  // verify command — therefore failed with `spawnSync npm ENOENT` on every
+  // Windows install, and the gate reported it as a plain non-zero verification
+  // rather than as an environment problem.
+  //
+  // Node's `shell: true` rebuilds the command line as `[file, ...args].join(" ")`
+  // and passes it to cmd.exe verbatim. That reconstruction is normally lossy —
+  // it does not quote an argument containing a space — but it is exact here,
+  // because these tokens were produced by splitting on whitespace in the first
+  // place. It is also only reached when the command contains no shell
+  // metacharacter, since those take the execSync branch above. An array command
+  // is excluded: its elements may legitimately contain spaces.
+  const winShim = tokenized && process.platform === "win32";
+
   if (!binary && !useShell) {
     if (opts.ignoreError) return { status: 0, stdout: "", stderr: "" };
     throw new GateError("Empty command provided");
@@ -61,7 +80,7 @@ export function runCmd(command, opts = {}) {
       : execFileSync(binary, args, {
           cwd,
           encoding: "utf-8",
-          shell: false,
+          shell: winShim,
           stdio: ["ignore", "pipe", "pipe"],
           env: opts.env || process.env,
           timeout,

package/src/scaffold.mjs

@@ -0,0 +1,146 @@
+import { existsSync, mkdirSync, readdirSync, copyFileSync, readFileSync, appendFileSync, writeFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const KIT_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+/**
+ * Paths the kit writes at runtime and must never hand to its own gate.
+ *
+ * Without these, `agentctl init` left every ledger, evidence manifest and
+ * telemetry line untracked in the working tree. The gate audits that tree, so
+ * the kit's own bookkeeping showed up as a diff the agent was accused of
+ * making: first as scope violations against `.agent/config.yml`, then — once
+ * enough evidence files accumulated — as a CRITICAL secret verdict. A new user
+ * met both before dispatching a single task.
+ */
+export const RUNTIME_GITIGNORE_ENTRIES = [
+  ".env",
+  ".agent/history/",
+  ".agent/state/",
+  ".agent/evidence/",
+  ".agent/handovers/",
+  ".agent/jules-queue/.state/",
+  ".agent/jules-queue/failed/",
+  ".agent/jules-queue/.processing/",
+  ".agent/jules-queue/completed/",
+  // A queued envelope is work-in-flight, not source. `.agent/jules-queue/**` is
+  // on the gate's deny list, so tracking the envelopes means the first gate
+  // after `task create` rejects the tree for the file `task create` just wrote.
+  // The negation has to follow the pattern it re-includes.
+  ".agent/jules-queue/*.md",
+  "!.agent/jules-queue/README.md",
+];
+
+/**
+ * Ensure `.gitignore` lists every runtime path in {@link RUNTIME_GITIGNORE_ENTRIES}.
+ *
+ * @param {string} root
+ * @returns {string[]} Entries newly appended (empty when already covered).
+ */
+export function ensureGitignore(root) {
+  const gitignorePath = join(root, ".gitignore");
+  const current = existsSync(gitignorePath) ? readFileSync(gitignorePath, "utf-8") : "";
+  const lines = new Set(current.split("\n").map((l) => l.trim()));
+  const missing = RUNTIME_GITIGNORE_ENTRIES.filter((e) => !lines.has(e));
+  if (missing.length === 0) return [];
+
+  const prefix = current && !current.endsWith("\n") ? "\n" : "";
+  appendFileSync(
+    gitignorePath,
+    `${prefix}\n# Jules Orchestrator runtime state & credentials\n${missing.join("\n")}\n`,
+    "utf-8"
+  );
+  return missing;
+}
+
+/**
+ * Copy every file from a directory shipped in the package into the target repo.
+ *
+ * @param {string} srcDir
+ * @param {string} destDir
+ * @param {boolean} force
+ * @returns {number} Files written.
+ */
+function copyDir(srcDir, destDir, force) {
+  if (!existsSync(srcDir) || srcDir === destDir) return 0;
+  mkdirSync(destDir, { recursive: true });
+  let written = 0;
+  for (const file of readdirSync(srcDir)) {
+    const src = join(srcDir, file);
+    const dest = join(destDir, file);
+    if (!existsSync(dest) || force) {
+      copyFileSync(src, dest);
+      written++;
+    }
+  }
+  return written;
+}
+
+/**
+ * Scaffold the repository assets the CLI's documented features depend on.
+ *
+ * This is the single source of truth for both entry points. `agentctl init`
+ * and `jules-init` used to scaffold different things: only the latter wrote
+ * AGENTS.md, the role prompts and the guardrails, while the README's quickstart
+ * pointed at the former. Anyone following the quickstart got a Jules that never
+ * saw the protocol and a `--role` flag with nothing to resolve against.
+ *
+ * Existing files are preserved unless `force` is set — re-running init is a
+ * routine way to pick up new presets and must not overwrite local edits.
+ *
+ * @param {string} [root=process.cwd()]
+ * @param {{ force?: boolean }} [options]
+ * @returns {{ created: string[], gitignore: string[] }}
+ */
+export function scaffoldRepoAssets(root = process.cwd(), options = {}) {
+  const force = Boolean(options.force);
+  const created = [];
+
+  const agentDir = join(root, ".agent");
+  const queueDir = join(agentDir, "jules-queue");
+  for (const d of [agentDir, queueDir, join(queueDir, "completed"), join(agentDir, "rules"), join(agentDir, "prompts"), join(agentDir, "workflows")]) {
+    if (!existsSync(d)) mkdirSync(d, { recursive: true });
+  }
+
+  // AGENTS.md is how the agent learns the protocol at all, so an existing file
+  // is appended to rather than replaced: repositories that already brief their
+  // agents must not lose that briefing to a scaffolding step.
+  const agentsFile = join(root, "AGENTS.md");
+  const template = join(KIT_ROOT, "JULES_RULES_TEMPLATE.md");
+  if (existsSync(template) && template !== agentsFile) {
+    if (!existsSync(agentsFile) || force) {
+      copyFileSync(template, agentsFile);
+      created.push("AGENTS.md");
+    } else if (!readFileSync(agentsFile, "utf-8").includes("<MCP_DIRECTIVE>")) {
+      appendFileSync(agentsFile, `\n\n---\n\n${readFileSync(template, "utf-8")}`, "utf-8");
+      created.push("AGENTS.md (appended)");
+    }
+  }
+
+  if (copyDir(join(KIT_ROOT, ".agent/prompts"), join(agentDir, "prompts"), force) > 0) {
+    created.push(".agent/prompts/ (Overseer, Bolt, Sentinel, Janitor)");
+  }
+  if (copyDir(join(KIT_ROOT, ".agent/rules"), join(agentDir, "rules"), force) > 0) {
+    created.push(".agent/rules/");
+  }
+  if (copyDir(join(KIT_ROOT, ".agent/workflows"), join(agentDir, "workflows"), force) > 0) {
+    created.push(".agent/workflows/");
+  }
+
+  // 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");
+  if (!existsSync(queueReadme)) {
+    writeFileSync(
+      queueReadme,
+      "# Task Queue\n\nEach `TASK-*.md` here is one queued task envelope.\n\n" +
+        "- `agentctl task create` writes them\n- `agentctl queue` dispatches them\n" +
+        "- Dispatched envelopes move to `completed/`; failures stay put for a re-run\n",
+      "utf-8"
+    );
+    created.push(".agent/jules-queue/README.md");
+  }
+
+  return { created, gitignore: ensureGitignore(root) };
+}

package/src/security.mjs

@@ -454,8 +454,26 @@ function secretScanVariants(addedLines) {
 // get encoded into a single CI variable.
 const BASE64_CANDIDATE = /[A-Za-z0-9+/\-_]{20,}={0,2}/g;
 
+// Budgets the decoder spends before it gives up and reports `capped`.
+//
+// The count that matters is payloads *retained* — blobs that decoded to text
+// and so could be carrying a credential. Counting every token that merely
+// matches the base64 alphabet instead made a digest indistinguishable from a
+// payload: a sha256 hex string is 64 characters of that alphabet, decodes to
+// binary, gets discarded, and used to consume a slot anyway. Any diff holding
+// 65 hashes — every lockfile bump — then tripped the cap and failed closed as
+// a CRITICAL credential leak with no credential anywhere in it.
 const BASE64_MAX_CANDIDATES = 64;
+const BASE64_MAX_TOKENS_EXAMINED = 8192;
 const BASE64_MAX_DECODED_BYTES = 64 * 1024;
+// Per-blob ceiling, so one oversized payload cannot spend the whole budget and
+// starve the blobs after it. The trade-off is deliberate: a credential buried
+// past 8 KB inside a single blob is missed, where the old code caught it only
+// by refusing to decode and then failing the entire diff closed. That refusal
+// fired on every checked-in base64 asset, and a gate that cries wolf on
+// ordinary input gets switched off. The cleartext scanners still run over the
+// raw diff regardless.
+const BASE64_MAX_BLOB_BYTES = 8 * 1024;
 
 /**
  * Share of characters that are printable ASCII (plus tab/newline/return).
@@ -480,14 +498,15 @@ function printableRatio(str) {
 function decodeBase64Blobs(text, onDecoded) {
   if (!text) return { decoded: [], capped: false };
   const decoded = [];
-  let candidates = 0;
+  let examined = 0;
+  let retained = 0;
   let bytes = 0;
   let capped = false;
 
   BASE64_CANDIDATE.lastIndex = 0;
   let match;
   while ((match = BASE64_CANDIDATE.exec(text)) !== null) {
-    if (candidates++ >= BASE64_MAX_CANDIDATES) {
+    if (examined++ >= BASE64_MAX_TOKENS_EXAMINED) {
       capped = true;
       break;
     }
@@ -497,10 +516,17 @@ function decodeBase64Blobs(text, onDecoded) {
       stdBlob += "=";
     }
 
-    if (bytes + (stdBlob.length * 3) / 4 > BASE64_MAX_DECODED_BYTES) {
+    // An oversized blob is decoded up to a bounded prefix rather than skipped
+    // outright. Base64 decodes in independent 4-character groups, so a prefix
+    // is exact, and a credential near the head of a large payload still
+    // surfaces — where skipping used to hide it and then blame the whole diff.
+    const budget = Math.min(BASE64_MAX_BLOB_BYTES, BASE64_MAX_DECODED_BYTES - bytes);
+    if (budget <= 0) {
       capped = true;
-      continue;
+      break;
     }
+    const maxChars = Math.floor(budget / 3) * 4;
+    if (stdBlob.length > maxChars) stdBlob = stdBlob.slice(0, maxChars);
 
     let plain;
     try {
@@ -509,8 +535,16 @@ function decodeBase64Blobs(text, onDecoded) {
       continue;
     }
     bytes += plain.length;
+
+    // A blob that decodes to binary has been examined and cleared. It is not a
+    // blind spot, so it must not spend a payload slot.
     if (printableRatio(plain) < 0.9) continue;
 
+    if (retained++ >= BASE64_MAX_CANDIDATES) {
+      capped = true;
+      break;
+    }
+
     decoded.push(plain);
     if (onDecoded) onDecoded(plain, rawBlob);
 
@@ -543,35 +577,141 @@ export function hasEncodedSecret(text) {
   return result.decoded.some((plain) => hasHighConfidenceSecret(plain));
 }
 
-export function scanDiff(diffTextStr = "", options = {}) {
-  if (!diffTextStr) return { ok: true, findings: [] };
-  const addedLines = diffTextStr
-    .split("\n")
-    .filter((line) => line.startsWith("+") && !line.startsWith("+++"))
-    .map((line) => line.slice(1))
-    .join("\n");
+/**
+ * Group the added lines of a unified diff by the file they belong to.
+ *
+ * Line numbers come from the `@@` hunk headers and count the post-image, so a
+ * reported number matches what an editor shows after the change is applied.
+ * Both the file and the number are best-effort: a fragment with no headers —
+ * the shape `wizard-task.mjs` synthesises from a prompt — yields one anonymous
+ * segment, which is exactly the old whole-diff behaviour.
+ *
+ * @param {string} diffText
+ * @returns {Array<{ file: string|null, lines: Array<{ text: string, no: number|null }> }>}
+ */
+function splitDiffByFile(diffText) {
+  const byFile = new Map();
+  let current = null;
+  let lineNo = null;
+
+  const select = (file) => {
+    if (!byFile.has(file)) byFile.set(file, { file, lines: [] });
+    current = byFile.get(file);
+  };
 
+  for (const line of diffText.split("\n")) {
+    if (line.startsWith("+++")) {
+      const name = line.slice(3).split("\t")[0].trim().replace(/^b\//, "");
+      select(name && name !== "/dev/null" ? name : null);
+      lineNo = null;
+      continue;
+    }
+    const hunk = /^@@ -\d+(?:,\d+)? \+(\d+)/.exec(line);
+    if (hunk) {
+      lineNo = Number(hunk[1]);
+      continue;
+    }
+    if (line.startsWith("+")) {
+      if (!current) select(null);
+      current.lines.push({ text: line.slice(1), no: lineNo });
+      if (lineNo !== null) lineNo++;
+    } else if (lineNo !== null && !line.startsWith("-") && !line.startsWith("\\")) {
+      lineNo++; // A context line advances the post-image just as an added one does.
+    }
+  }
+
+  return [...byFile.values()].filter((s) => s.lines.length > 0);
+}
+
+/**
+ * Classify a block of added lines. Returns the single most severe finding, or
+ * null when the block is clean.
+ *
+ * @param {string} addedLines
+ * @returns {{ severity: string, type: string, description: string, encoded: boolean }|null}
+ */
+function classifyAddedLines(addedLines) {
   const { all: variants, normalized } = secretScanVariants(addedLines);
-  const hasHigh = variants.some((v) => hasHighConfidenceSecret(v));
+  if (variants.some((v) => hasHighConfidenceSecret(v))) {
+    return { severity: "CRITICAL", type: "HIGH_CONFIDENCE_SECRET", encoded: false, description: "High-confidence secret pattern detected in added diff lines" };
+  }
   // Only worth decoding when nothing was found in the clear, and only against
   // the fully-normalised text: decoding is the expensive step, and the
   // intermediate variants differ from it in ways base64 blobs do not care about.
-  const hasEncoded = !hasHigh && hasEncodedSecret(normalized);
-  const hasLow = !hasHigh && !hasEncoded && variants.some((v) => hasLowConfidenceSecret(v));
-  const findings = [];
-
-  if (hasHigh) {
-    findings.push({ severity: "CRITICAL", type: "HIGH_CONFIDENCE_SECRET", description: "High-confidence secret pattern detected in added diff lines" });
-  } else if (hasEncoded) {
+  if (hasEncodedSecret(normalized)) {
     // Same type as the cleartext case: every gate that blocks on
     // HIGH_CONFIDENCE_SECRET should block on this too, and a new type would
     // have silently passed through the ones not updated. The description
     // carries the difference the operator needs.
-    findings.push({ severity: "CRITICAL", type: "HIGH_CONFIDENCE_SECRET", description: "High-confidence secret pattern detected inside a base64-encoded value on an added diff line" });
-  } else if (hasLow) {
-    findings.push({ severity: "HIGH", type: "LOW_CONFIDENCE_SECRET", description: "Low-confidence secret or authorization token detected in added diff lines" });
+    return { severity: "CRITICAL", type: "HIGH_CONFIDENCE_SECRET", encoded: true, description: "High-confidence secret pattern detected inside a base64-encoded value on an added diff line" };
+  }
+  if (variants.some((v) => hasLowConfidenceSecret(v))) {
+    return { severity: "HIGH", type: "LOW_CONFIDENCE_SECRET", encoded: false, description: "Low-confidence secret or authorization token detected in added diff lines" };
+  }
+  return null;
+}
+
+/**
+ * Narrow a segment-level finding to the line that produced it.
+ *
+ * Only runs on a segment that has already been flagged, so the extra pass costs
+ * nothing on a clean diff. Returns null when no single line reproduces the
+ * verdict — a credential split across a concatenation belongs to the block, not
+ * to either half of it, and guessing one of them would point the operator at an
+ * innocent line.
+ *
+ * @param {Array<{ text: string, no: number|null }>} lines
+ * @param {string} type
+ * @returns {number|null}
+ */
+function locateFindingLine(lines, type) {
+  for (const line of lines) {
+    if (line.no === null) continue;
+    const hit = classifyAddedLines(line.text);
+    if (hit && hit.type === type) return line.no;
+  }
+  return null;
+}
+
+export function scanDiff(diffTextStr = "", options = {}) {
+  if (!diffTextStr) return { ok: true, findings: [] };
+
+  const segments = splitDiffByFile(diffTextStr);
+  const findings = [];
+
+  for (const segment of segments) {
+    const hit = classifyAddedLines(segment.lines.map((l) => l.text).join("\n"));
+    if (!hit) continue;
+    const line = segment.file ? locateFindingLine(segment.lines, hit.type) : null;
+    const at = segment.file ? ` (${segment.file}${line ? `:${line}` : ""})` : "";
+    findings.push({
+      severity: hit.severity,
+      type: hit.type,
+      file: segment.file,
+      line,
+      description: `${hit.description}${at}`,
+    });
+  }
+
+  // Scanning per file loses anything that only matches across a file boundary,
+  // which the previous whole-diff join happened to catch. Rather than trade
+  // detection for attribution, fall back to the joined text when every file
+  // came back clean — the cost lands only on diffs with nothing to report.
+  if (findings.length === 0 && segments.length > 1) {
+    const hit = classifyAddedLines(segments.flatMap((s) => s.lines.map((l) => l.text)).join("\n"));
+    if (hit) {
+      findings.push({
+        severity: hit.severity,
+        type: hit.type,
+        file: null,
+        line: null,
+        description: `${hit.description} (spanning more than one file)`,
+      });
+    }
   }
 
+  const secretsOk = findings.length === 0;
+
   const edgeRes = checkEdgeRuntimeImports(diffTextStr, options);
   if (!edgeRes.ok) {
     for (const v of edgeRes.violations) {
@@ -583,12 +723,12 @@ export function scanDiff(diffTextStr = "", options = {}) {
   const crossPkgRes = checkCrossPackageImports(diffTextStr, root, options);
   if (!crossPkgRes.ok) {
     for (const v of crossPkgRes.violations) {
-      findings.push({ severity: "HIGH", type: "CROSS_PACKAGE_BOUNDARY_VIOLATION", description: v.reason });
+      findings.push({ severity: "HIGH", type: "CROSS_PACKAGE_BOUNDARY_VIOLATION", file: v.file ?? null, description: v.reason });
     }
   }
 
   return {
-    ok: !hasHigh && !hasEncoded && !hasLow && edgeRes.ok && crossPkgRes.ok,
+    ok: secretsOk && edgeRes.ok && crossPkgRes.ok,
     findings,
   };
 }

package/src/task-optimizer.mjs

@@ -280,7 +280,7 @@ export function scorePromptFalsifiability(promptText, options = {}) {
   } else if (!verifyCmd) {
     score -= 15;
     issues.push({ type: "MISSING_ORACLE", message: "No automated test or build verification command specified.", penalty: 15 });
-    suggestions.push("Specify a verification command using --verify (e.g. 'npm test').");
+    suggestions.push("Specify a verification command using --verify-cmd (e.g. 'npm test').");
   }
 
   // Final score clamping & letter grade assignment