jules-orchestrator-kit 0.64.0 → 0.65.0

package/README.md

@@ -49,12 +49,15 @@
 <a id="quickstart"></a>
 ## Quickstart
 
-Get running in any repository in 3 commands (zero configuration required):
+Get running in any repository in 3 commands. `init` asks seven questions and
+fills in a sensible answer for each; `--yes` accepts all of them, detects the
+stack, and probes the test command it picked before writing it down.
 
 ```bash
 # 1. Scaffold config, AGENTS.md, role prompts and guardrails
 #    (auto-detects Python, Rust, Go, Node, PHP, etc.)
-npx jules-orchestrator-kit init
+#    Drop --yes to choose provider, plan, profile and workflows yourself.
+npx jules-orchestrator-kit init --yes
 ```
 
 ```bash
@@ -204,7 +207,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 **1085 unit tests across 150 suites passing in < 15.0s**.
+* **Verified Test Suite:** Tested with **1109 unit tests across 154 suites passing in < 15.0s**.
 
 <br/>
 

package/bin/agentctl.mjs

@@ -429,6 +429,11 @@ async function main() {
           if (p.violations) {
             p.violations.forEach((v) => console.log(`     - Violation: ${v.file} (Rule: ${v.rule})`));
           }
+          if (p.setup) {
+            console.log(`     - Setup: accepted ${p.setup.length} gate scaffold file(s) this repository did not have yet`);
+            p.setup.forEach((f) => console.log(`         ${f}`));
+            console.log(`       Commit them to the base branch and the full protect rules apply from then on.`);
+          }
           if (p.findings) {
             p.findings.forEach((f) => console.log(`     - [${f.severity}] ${f.type}: ${f.description}`));
           }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jules-orchestrator-kit",
-  "version": "0.64.0",
+  "version": "0.65.0",
   "description": "Zero-dependency safety gatekeeper, test oracle generator, and multi-agent coordination protocol for autonomous coding agents — Google Jules, Claude Code, Codex and Gemini CLI.",
   "repository": {
     "type": "git",

package/scripts/guard-reach-check.mjs

@@ -51,6 +51,7 @@ import {
   TAMPER_CANARIES,
   PREDICATE_MUTANTS,
   EMPTY_RUN_CANARIES,
+  COUNTED_RUN_CANARIES,
   SCOPE_CANARIES,
   INNOCENT_EDITS,
   UNREADABLE_DIALECTS,
@@ -105,6 +106,17 @@ const add = (name, ok, detail) => {
 
 {
   const missed = EMPTY_RUN_CANARIES.filter((c) => parseCollectedTests(c.output, "").count !== 0);
+  const undercounted = COUNTED_RUN_CANARIES.filter((c) => {
+    const n = parseCollectedTests(c.output, "").count;
+    return n === null || n < c.atLeast;
+  });
+  add(
+    "policy: a stated count is never read as empty",
+    undercounted.length === 0,
+    undercounted.length
+      ? undercounted.map((c) => `${c.id} (${c.why})`).join("; ")
+      : `${COUNTED_RUN_CANARIES.length} healthy runs counted, not rejected`
+  );
   add(
     "policy: empty-run detection",
     missed.length === 0,

package/src/engine.mjs

@@ -204,6 +204,16 @@ export async function gate(opts = {}) {
           // Read from the base commit like every other trusted field: an
           // uncommitted `required: false` must not be able to switch the gate off.
           required: parsed.verify?.required !== undefined ? parsed.verify.required !== false : config.verify.required !== false,
+          // The floor the collection check applies. Omitting it here meant
+          // `verify.minTests` was silently dropped and always defaulted to 1
+          // — while the failure message told the operator to set exactly
+          // that. A remediation hint that does nothing is worse than none.
+          minTests:
+            parsed.verify?.minTests !== undefined
+              ? parsed.verify.minTests
+              : parsed.verify?.min_tests !== undefined
+                ? parsed.verify.min_tests
+                : config.verify.minTests,
           scope: parsed.verify?.scope || config.verify.scope || "global",
           timeoutMs: parsed.verify?.timeoutMs || parsed.verify?.timeout_ms || config.verify.timeoutMs,
         };
@@ -249,7 +259,45 @@ export async function gate(opts = {}) {
     violation.file = link;
   }
 
-  phases.push({ phase: "scope", ok: scopeResult.ok, violations: scopeResult.violations });
+  // Bootstrap: the files that bring a repository under the gate are not agent
+  // edits to the gate.
+  //
+  // `init` writes `.agent/**` and then tells the user to commit it. Doing
+  // exactly that produced Exit 3 on the very first run, because the base
+  // branch does not have the commit yet and every scaffolded path matches
+  // BUILTIN_PROTECT or BUILTIN_DENY. The advice printed alongside it was
+  // `--allow-protected` — so a newcomer's first lesson was how to switch the
+  // scope guard off. A gate that refuses its own installation is not strict,
+  // it is broken.
+  //
+  // Narrow on purpose, and only where it cannot weaken anything: the base
+  // commit must have no gate config at all — in which case `trustedScope` is
+  // already built-ins only and nothing in the added files is trusted — and
+  // every violating path must be scaffold that the base does not have. A
+  // repository already under the gate keeps the full rule, so an agent still
+  // cannot touch the policy it is governed by.
+  let acceptedScaffold = [];
+  if (!scopeResult.ok && !trustedConfigRaw) {
+    const violations = scopeResult.violations || [];
+    const isScaffold = (f) => typeof f === "string" && f.replace(/\\/g, "/").startsWith(".agent/");
+    if (
+      violations.length > 0 &&
+      violations.every((v) => isScaffold(v.file) && showFromOrigin(root, base, v.file) === null)
+    ) {
+      acceptedScaffold = violations.map((v) => v.file);
+      scopeResult.violations = [];
+      scopeResult.ok = true;
+    }
+  }
+
+  phases.push({
+    phase: "scope",
+    ok: scopeResult.ok,
+    violations: scopeResult.violations,
+    // Reported, never silent: the operator has to see that the gate accepted
+    // files it would otherwise have blocked, and why.
+    ...(acceptedScaffold.length > 0 ? { setup: acceptedScaffold } : {}),
+  });
   appendTelemetry(root, "gate_phase", { phase: "scope", ok: scopeResult.ok });
   if (progressBus && progressToken) {
     progressBus.reportProgress(progressToken, 25, 100, "Phase 1/4: Scope Guard verification complete");

package/src/guard-policy.mjs

@@ -479,3 +479,34 @@ IMPORT_EXTRACTION_CASES.push(
     why: "same, in the other place examples live",
   }
 );
+
+/**
+ * Runs that stated a count, which must never be read as empty.
+ *
+ * The floor was written to be one-sided — only a *stated* zero fails — and
+ * then a phrase was allowed to outrank a statement. A healthy 190-test TAP
+ * suite whose one skipped fixture printed `# SKIP no tests found` was
+ * rejected as empty and attributed to Jest, in a repository that does not
+ * use Jest. A false red on a correct repository is how a user learns the
+ * gate is broken and turns it off.
+ */
+export const COUNTED_RUN_CANARIES = [
+  {
+    id: "tap with a skip message",
+    output: "TAP version 13\n# Subtest: performance\n    # SKIP no tests found\nok 1 - performance # SKIP\n1..191\n# tests 191\n# pass 190\n# skip 1",
+    atLeast: 1,
+    why: "`no tests found` inside a skip comment is not a statement about the run",
+  },
+  {
+    id: "pytest mentioning an empty module",
+    output: "collected 12 items\n\ntests/test_a.py ............\n\n12 passed in 0.3s",
+    atLeast: 1,
+    why: "a stated count is present and must win",
+  },
+  {
+    id: "go, verbose, two tests",
+    output: "--- PASS: TestAdd (0.00s)\n--- PASS: TestSub (0.00s)\nok  \texample.com/lib\t0.004s",
+    atLeast: 1,
+    why: "Go's own `ok  <package>` line, which a bare `^ok\\s` confused with TAP's `ok 1 - name`",
+  },
+];

package/src/ops/test-collection.mjs

@@ -71,8 +71,15 @@ const EXPLICIT_ZERO = [
 
 /** Go prints this per package that has no test files at all. */
 const GO_NO_TEST_FILES = /\[no test files\]/;
-/** Any sign that a Go package did run tests. */
-const GO_RAN_SOMETHING = /^(?:ok|FAIL|---\s+(?:PASS|FAIL|SKIP)):?\s/m;
+/**
+ * Any sign that a Go package did run tests.
+ *
+ * The negative lookahead is what separates Go from TAP. `ok 1 - performance`
+ * is a TAP result line and `ok  example.com/lib 0.004s` is a Go package
+ * summary, and a bare `^ok\s` matched both — so a 190-test TAP suite was
+ * classified as Go and reported as having stated no count at all.
+ */
+const GO_RAN_SOMETHING = /^(?:(?:ok|FAIL)\s+(?!\d+\s)\S+|---\s+(?:PASS|FAIL|SKIP):?\s)/m;
 
 /**
  * Read a collected-test count out of a runner's output.
@@ -87,8 +94,20 @@ export function parseCollectedTests(stdout = "", stderr = "") {
   const text = `${stdout || ""}\n${stderr || ""}`;
   if (!text.trim()) return { count: null, runner: null };
 
-  for (const rule of EXPLICIT_ZERO) {
-    if (rule.re.test(text)) return { count: 0, runner: rule.name };
+  // A stated count wins over a phrase that merely resembles one.
+  //
+  // `EXPLICIT_ZERO` used to be consulted first, so any output containing the
+  // words "no tests found" was read as a zero — including a healthy TAP run
+  // of 190 passing tests whose one skipped fixture printed
+  // `# SKIP no tests found`. The gate rejected the suite as empty and named
+  // Jest as the runner, in a repository that does not use Jest. A phrase
+  // appears anywhere in a stream; a count is stated deliberately, so the
+  // count is the better witness and has to be asked first.
+  for (const rule of COUNT_PATTERNS) {
+    const m = rule.re.exec(text);
+    if (!m) continue;
+    const n = Number(m[1]);
+    if (Number.isFinite(n)) return { count: n, runner: rule.name };
   }
 
   // Go states absence per package rather than as a count, so it needs its own
@@ -104,11 +123,9 @@ export function parseCollectedTests(stdout = "", stderr = "") {
     return { count: perTest && perTest.length > 0 ? perTest.length : null, runner: "go" };
   }
 
-  for (const rule of COUNT_PATTERNS) {
-    const m = rule.re.exec(text);
-    if (!m) continue;
-    const n = Number(m[1]);
-    if (Number.isFinite(n)) return { count: n, runner: rule.name };
+  // Only now: no runner stated a number, so a declared absence is all there is.
+  for (const rule of EXPLICIT_ZERO) {
+    if (rule.re.test(text)) return { count: 0, runner: rule.name };
   }
 
   return { count: null, runner: null };

package/src/stack-detector.mjs

@@ -188,6 +188,56 @@ export function detectEdgeRuntime(projectRoot = process.cwd()) {
 /**
  * Detects 24+ polyglot stacks and container environments.
  */
+/**
+ * Test commands worth trying, best first, when the detected one does not run.
+ *
+ * `init` probes the command it picked. On a repository whose Makefile
+ * declares a `test` target that needs a build environment the machine does
+ * not have, that probe failed, printed `Oracle verification probe failed`,
+ * and the wizard wrote the broken command into the config anyway — in a
+ * repository where `pytest` was on PATH and all 360 tests passed in 1.3s.
+ * Measuring something and then ignoring the measurement is worse than not
+ * measuring: it produces a hard red on day one, which is how a user learns
+ * the gate is broken and turns it off.
+ *
+ * Kept deliberately generic — a per-ecosystem convention, never a per-project
+ * or per-provider guess.
+ *
+ * @param {string} root
+ * @param {string} [detected] - the command detection chose; always first.
+ * @returns {string[]} ordered, de-duplicated candidates
+ */
+export function oracleCandidates(root = process.cwd(), detected = "") {
+  const out = [];
+  const push = (c) => {
+    const v = (c || "").trim();
+    if (v && !out.includes(v) && !isPlaceholderTestScript(v)) out.push(v);
+  };
+  const has = (f) => existsSync(join(root, f));
+
+  push(detected);
+
+  if (has("package.json")) {
+    try {
+      const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf-8"));
+      if (pkg.scripts?.test && !isPlaceholderTestScript(pkg.scripts.test)) push("npm test");
+    } catch (_) {}
+  }
+  if (has("pytest.ini") || has("pyproject.toml") || has("setup.py") || has("tox.ini") || has("setup.cfg")) {
+    push(pytestCmd());
+  }
+  if (has("Cargo.toml")) push("cargo test");
+  if (has("go.mod")) push("go test ./...");
+  if (has("Gemfile")) push("bundle exec rspec");
+  if (has("composer.json")) push("./vendor/bin/phpunit");
+  if (has("pom.xml")) push("mvn -q test");
+  if (has("build.gradle") || has("build.gradle.kts")) push("./gradlew test");
+  if (has("pubspec.yaml")) push("dart test");
+  if (has("Package.swift")) push("swift test");
+
+  return out;
+}
+
 export function detectPolyglotStack(projectRoot = process.cwd()) {
   const edgeInfo = detectEdgeRuntime(projectRoot);
   const isDevcontainer = existsSync(join(projectRoot, ".devcontainer", "devcontainer.json"));

package/src/wizard-init.mjs

@@ -3,7 +3,7 @@ import { join } from "node:path";
 import { parseYaml, TIER_PRESETS, VENDOR_TIERS, FALLBACK_TIER } from "./config.mjs";
 import { suggestProvider, detectAvailableProviders } from "./provider-readiness.mjs";
 import { detectDefaultBranch } from "./git.mjs";
-import { resolveWorkspaceBoundary } from "./stack-detector.mjs";
+import { resolveWorkspaceBoundary, oracleCandidates } from "./stack-detector.mjs";
 import { PROFILE_NAMES, PROFILE_DESCRIPTIONS } from "./profiles.mjs";
 import { detectStackOracles, runVerificationProbe } from "./wizard-oracle.mjs";
 import { select, multiSelect, input, confirm, spinner, isTTY } from "./tui.mjs";
@@ -302,6 +302,51 @@ export function loadPresets(root = process.cwd()) {
  * @param {object} [options]
  * @returns {Promise<{ ok: boolean, configPath: string, plan: object }>}
  */
+/**
+ * Probe the chosen test command, and take detection's next choice if it fails.
+ *
+ * Runs on the non-interactive path too. `--yes` means "do not ask me", not
+ * "do not check" — and the user who is not watching is exactly the one who
+ * cannot notice that the command written into their config does not run.
+ * Before this, the probe lived inside the interactive branch, so
+ * `agentctl init --yes` wrote `make test` into a repository where `make test`
+ * exits 2 and `npm test` passes, and the first gate run was a hard red.
+ *
+ * @returns {Promise<string>} the command to save
+ */
+async function resolveRunnableOracle(root, testCmd, options = {}) {
+  if (!testCmd) return 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)`);
+    return testCmd;
+  }
+  probeSp.fail(`Oracle verification probe failed (Exit ${probeRes.code})`);
+
+  const alternates = oracleCandidates(root, testCmd).filter((c) => c !== testCmd).slice(0, 3);
+  for (const cand of alternates) {
+    const altSp = spinner(`Trying ${cand}`, options);
+    const altRes = await runVerificationProbe(cand, root);
+    if (altRes.ok) {
+      altSp.stop(`${cand} runs here (${altRes.durationMs}ms) — using it instead`);
+      return cand;
+    }
+    altSp.fail(`${cand} also failed (Exit ${altRes.code})`);
+  }
+
+  // Nothing runs. Say so in terms the user can act on, rather than leaving a
+  // failed spinner to scroll past and a broken command in the config.
+  const out = options.stdout || process.stdout;
+  out.write("\n");
+  out.write("   \u26a0\ufe0f  No test command could be run in this environment.\n");
+  out.write(`      Keeping "${testCmd}" \u2014 the gate will fail until it runs here.\n`);
+  out.write("      Point verify.test in .agent/config.yml at a command that works,\n");
+  out.write("      or, if this repository genuinely has no suite, set\n");
+  out.write("      verify.required: false deliberately rather than by accident.\n\n");
+  return testCmd;
+}
+
 export async function runInitWizard(root = process.cwd(), options = {}) {
   const interactive = options.interactive !== false && isTTY(options.stdin || process.stdin);
 
@@ -322,6 +367,7 @@ export async function runInitWizard(root = process.cwd(), options = {}) {
   let selectedProvider = options.provider || existingConfig.provider;
   let selectedProfile = options.profile || existingConfig.verify?.profile;
   let testCmd = options.testCmd;
+  let probeInteractive = null;
   let buildCmd = options.buildCmd;
   let selectedPresets = options.presets;
 
@@ -402,16 +448,20 @@ export async function runInitWizard(root = process.cwd(), options = {}) {
 
     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})`);
-      }
-    }
+    probeInteractive = await confirm("Run verification probe on test command before saving?", true, options);
+  }
+
+  // The probe runs whether or not anyone was asked: interactive users can
+  // decline it, but silence from `--yes` is not a decline.
+  if (probeInteractive !== false && options.probe !== false) {
+    // Resolve the command the way planInit will, or there is nothing to
+    // probe: on the headless path `testCmd` stays undefined until planInit
+    // fills it in from detection, so the probe silently examined nothing —
+    // the exact fail-open shape this project keeps finding in itself.
+    const effective =
+      testCmd || existingConfig.verify?.test || detectStackOracles(root)?.candidates?.testCmd || "";
+    const adopted = await resolveRunnableOracle(root, effective, options);
+    if (adopted) testCmd = adopted;
   }
 
   // `...options` first, for the same reason as in wizard-task.mjs: spreading it