jules-orchestrator-kit 0.41.0 → 0.42.0

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