jules-orchestrator-kit 0.63.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 **1015 unit tests across 145 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.63.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",
@@ -56,7 +56,8 @@
     "jules:doc-sync": "node scripts/doc-sync-check.mjs",
     "release": "node scripts/release.mjs",
     "guard-reach": "node scripts/guard-reach-check.mjs",
-    "lint": "eslint ."
+    "lint": "eslint .",
+    "package-integrity": "node scripts/package-integrity-check.mjs"
   },
   "engines": {
     "node": ">=20.0.0"

package/scripts/guard-reach-check.mjs

@@ -27,7 +27,7 @@
  *
  * Three steps, all in-process, no dependencies, well under a second:
  *
- *   1. POLICY   — the hand-written witness table in test/fixtures/guard-policy.mjs
+ *   1. POLICY   — the hand-written witness table in src/guard-policy.mjs
  *                 must hold. It is derived from what the tool advertises, never
  *                 from the regexes that implement it.
  *   2. CANARIES — every known-bad input must produce the finding it names. A
@@ -51,15 +51,26 @@ import {
   TAMPER_CANARIES,
   PREDICATE_MUTANTS,
   EMPTY_RUN_CANARIES,
+  COUNTED_RUN_CANARIES,
   SCOPE_CANARIES,
-} from "../test/fixtures/guard-policy.mjs";
+  INNOCENT_EDITS,
+  UNREADABLE_DIALECTS,
+} from "../src/guard-policy.mjs";
 
-/** Build a unified diff for one canary. */
+/**
+ * Build a unified diff for one canary.
+ *
+ * The context line carries the comment syntax of the file's own language.
+ * A `//` line in a `.py` fixture is not a comment, and a fixture that lies
+ * about the language under test measures the fixture rather than the guard —
+ * which is how two false results were once read as two defects.
+ */
 function canaryDiff(c) {
-  const lines = [`--- a/${c.file}`, `+++ b/${c.file}`, "@@ -1,20 +1,20 @@", " // context"];
+  const ctx = c.context || "// context";
+  const lines = [`--- a/${c.file}`, `+++ b/${c.file}`, "@@ -1,20 +1,20 @@", ` ${ctx}`];
   for (const l of c.removed) lines.push(`-${l}`);
   for (const l of c.added) lines.push(`+${l}`);
-  lines.push(" // context");
+  lines.push(` ${ctx}`);
   return lines.join("\n");
 }
 
@@ -95,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,
@@ -107,6 +129,7 @@ const canaryResults = new Map();
 {
   const silent = [];
   const noDenominator = [];
+  const noAssertions = [];
   for (const c of TAMPER_CANARIES) {
     const res = checkTestTampering(canaryDiff(c));
     const hit = (res.violations || []).some((v) => v.type === c.expect);
@@ -114,12 +137,51 @@ const canaryResults = new Map();
     if (!hit) silent.push(`${c.id} expected ${c.expect}, got ${JSON.stringify((res.violations || []).map((v) => v.type))}`);
     // A finding with no denominator is the shape this script exists to reject.
     if (hit && !(res.inputsSeen > 0)) noDenominator.push(c.id);
+    // Counting lines was not enough: a JUnit diff reported one input examined
+    // and a clean PASS while every assertion in it went unrecognised. A rule
+    // about assertions has to say how many assertions it actually read.
+    if (hit && c.expect !== "TEST_SKIP_INJECTION" && !(res.assertionsSeen > 0)) {
+      noAssertions.push(`${c.id} (${res.assertionsSeen} assertions parsed)`);
+    }
   }
   add("canaries: every tamper rule still fires", silent.length === 0, silent.length ? silent.join("; ") : `${TAMPER_CANARIES.length} canaries red as required`);
   add("canaries: every finding carries a denominator", noDenominator.length === 0, noDenominator.length ? noDenominator.join(", ") : "inputsSeen > 0 on every hit");
+  add("canaries: assertion rules parsed an assertion", noAssertions.length === 0, noAssertions.length ? noAssertions.join(", ") : "assertionsSeen > 0 on every assertion finding");
+}
+
+// --- 3. The opposite failure: flagging what is innocent ---------------------
+{
+  const noisy = [];
+  for (const e of INNOCENT_EDITS) {
+    const res = checkTestTampering(canaryDiff(e));
+    const types = (res.violations || []).map((v) => v.type);
+    if (types.length > 0) noisy.push(`${e.id} → ${JSON.stringify(types)} (${e.why})`);
+  }
+  add(
+    "innocent edits stay silent",
+    noisy.length === 0,
+    noisy.length
+      ? noisy.join("; ")
+      : `${INNOCENT_EDITS.length} ordinary edits produce no finding`
+  );
+}
+
+{
+  const quiet = [];
+  for (const d of UNREADABLE_DIALECTS) {
+    const res = checkTestTampering(canaryDiff(d));
+    if (res.status !== "UNREADABLE") quiet.push(`${d.id} → ${res.status} (${d.why})`);
+  }
+  add(
+    "an unparsable dialect says so",
+    quiet.length === 0,
+    quiet.length
+      ? `${quiet.join("; ")} — coverage ending is fine, ending silently is not`
+      : `${UNREADABLE_DIALECTS.length} unsupported dialects reported, not passed`
+  );
 }
 
-// --- 3. Predicate mutants ---------------------------------------------------
+// --- 4. Predicate mutants ---------------------------------------------------
 {
   const survivors = [];
   for (const mutant of PREDICATE_MUTANTS) {

package/scripts/package-integrity-check.mjs

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+
+/**
+ * Does the package we publish actually work?
+ *
+ * Every test in this repository runs against the source tree, where every
+ * file is present by definition. What users install is a tarball built from
+ * the `files` list in package.json, and nothing checked that the two agreed.
+ *
+ * They did not. v0.63.0 shipped `scripts/guard-reach-check.mjs` — the check
+ * whose entire purpose is to prove no guard has silently gone missing —
+ * while leaving behind the policy contract it imports. Unpacked and run, it
+ * threw ERR_MODULE_NOT_FOUND. The CLI was fine, 1015 tests were green, nine
+ * CI cells passed, and the published artefact still had a hole in it,
+ * because every one of those signals was measured somewhere the file existed.
+ *
+ * This asks the packer what it would ship, and then resolves the import
+ * graph inside that answer.
+ *
+ * Usage: node scripts/package-integrity-check.mjs [--json]
+ * Exit codes: 0 = the tarball is self-contained, 1 = it is not.
+ */
+
+import { execFileSync } from "node:child_process";
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, dirname, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { IMPORT_EXTRACTION_CASES } from "../src/guard-policy.mjs";
+
+const root = fileURLToPath(new URL("..", import.meta.url));
+
+/**
+ * Mark every character that sits inside a string literal or a comment.
+ *
+ * Without this, an import quoted *inside* a fixture string reads as an
+ * import of the file itself — this check's first run reported six broken
+ * imports in the policy contract, all of them example text. A guard that
+ * cries wolf about its own fixtures gets switched off in a week.
+ *
+ * Approximate on purpose, and biased on purpose: a regex literal holding a
+ * quote can open a phantom string, so the counts reported below exist to
+ * make a mask that swallowed the file visible rather than silent.
+ */
+function stringMask(src) {
+  const mask = new Uint8Array(src.length);
+  let i = 0;
+  let quote = null;
+  let comment = null;
+  while (i < src.length) {
+    const c = src[i];
+    const d = src[i + 1];
+    if (comment === "line") {
+      if (c === "\n") comment = null;
+      else mask[i] = 1;
+      i++;
+      continue;
+    }
+    if (comment === "block") {
+      mask[i] = 1;
+      if (c === "*" && d === "/") {
+        mask[i + 1] = 1;
+        comment = null;
+        i += 2;
+        continue;
+      }
+      i++;
+      continue;
+    }
+    if (quote !== null) {
+      mask[i] = 1;
+      if (c === "\\") {
+        if (i + 1 < src.length) mask[i + 1] = 1;
+        i += 2;
+        continue;
+      }
+      if (c === quote) quote = null;
+      i++;
+      continue;
+    }
+    if (c === "/" && d === "/") { comment = "line"; mask[i] = 1; i++; continue; }
+    if (c === "/" && d === "*") { comment = "block"; mask[i] = 1; i++; continue; }
+    // A regex literal holding a quote — `/["']/` — opens a string that never
+    // closes, and everything after it is misread. This file's own subject
+    // matter is regexes full of quote characters, so the mask desynchronised
+    // and a `require("./calc")` written inside a comment was reported as a
+    // missing module. Deciding regex-versus-division on the previous token is
+    // the same approximation the diff scanner already makes.
+    if (c === "/") {
+      let k = i - 1;
+      while (k >= 0 && /\s/.test(src[k])) k--;
+      const prev = k >= 0 ? src[k] : "";
+      if (prev === "" || "(,=:[!&|?{};+-*%~^<>".includes(prev)) {
+        mask[i] = 1;
+        let j = i + 1;
+        let cls = false;
+        while (j < src.length) {
+          const e = src[j];
+          mask[j] = 1;
+          if (e === "\\") { if (j + 1 < src.length) mask[j + 1] = 1; j += 2; continue; }
+          if (e === "[") cls = true;
+          else if (e === "]") cls = false;
+          else if (e === "/" && !cls) { j++; break; }
+          else if (e === "\n") break;
+          j++;
+        }
+        i = j;
+        continue;
+      }
+    }
+    if (c === '"' || c === "'" || c === "`") { quote = c; mask[i] = 1; i++; continue; }
+    i++;
+  }
+  return mask;
+}
+
+/**
+ * Every module specifier in a source file.
+ *
+ * Deliberately newline-tolerant. A matcher bounded by `[^;\n]*?` cannot see
+ * a multi-line named import, which is exactly the import that was missing
+ * from the tarball, so the first version of this check certified the broken
+ * package as sound. The extraction cases in the policy contract exist to
+ * keep that from being a private mistake twice.
+ */
+export function extractSpecifiers(src, { skipQuoted = true } = {}) {
+  const mask = skipQuoted ? stringMask(src) : null;
+  const found = new Set();
+  const collect = (re) => {
+    for (const m of src.matchAll(re)) {
+      // What decides is the token immediately before the specifier — the
+      // `from`, or the `(` of a call. In a real import it is code; in a
+      // fixture it is the middle of a string. Testing the *keyword* instead
+      // was not enough: `export const CASES = [` at the top of a file
+      // matched lazily forward into the first `from "…"` inside an example,
+      // so a genuine keyword lent its authority to quoted text.
+      if (mask) {
+        let j = m.indices[1][0] - 2;
+        while (j >= 0 && /\s/.test(src[j])) j--;
+        if (j >= 0 && mask[j]) continue;
+      }
+      found.add(m[1]);
+    }
+  };
+  collect(/(?:^|[\s;}])(?:import|export)\s[\s\S]{0,500}?from\s*["']([^"']+)["']/gd);
+  collect(/(?:^|[\s;}])import\s*["']([^"']+)["']/gd);
+  collect(/\bimport\s*\(\s*["']([^"']+)["']/gd);
+  collect(/\brequire\s*\(\s*["']([^"']+)["']/gd);
+  return [...found];
+}
+
+/**
+ * Run every integrity check and return the result.
+ *
+ * Exported as a function rather than run on import: a module that checks the
+ * package must not exit the process of anything that merely imports it.
+ */
+export function checkPackageIntegrity() {
+  const failures = [];
+  const checks = [];
+  const add = (name, ok, detail) => {
+    checks.push({ name, ok, detail });
+    if (!ok) failures.push(`${name}: ${detail}`);
+  };
+
+  // --- 1. The extractor must be able to see what it claims to look for -------
+  {
+    const wrong = [];
+    for (const c of IMPORT_EXTRACTION_CASES) {
+      const got = extractSpecifiers(c.src).sort();
+      const want = [...c.expect].sort();
+      if (JSON.stringify(got) !== JSON.stringify(want)) {
+        wrong.push(`${c.id}: found ${JSON.stringify(got)}, contract says ${JSON.stringify(want)}`);
+      }
+    }
+    add("extractor: every import form is visible", wrong.length === 0, wrong.length ? wrong.join("; ") : `${IMPORT_EXTRACTION_CASES.length} forms found`);
+  }
+
+  // --- 2. Ask the packer what it would actually ship -------------------------
+  let shipped = new Set();
+  try {
+    const out = execFileSync("npm", ["pack", "--dry-run", "--json"], { cwd: root, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] });
+    shipped = new Set(JSON.parse(out)[0].files.map((f) => f.path.split(/[\\/]/).join("/")));
+  } catch (err) {
+    add("packer: `npm pack --dry-run` answers", false, err.message);
+  }
+  add("packer: the tarball is not empty", shipped.size > 0, `${shipped.size} files`);
+
+  // --- 3. Resolve the import graph inside the tarball ------------------------
+  {
+    const broken = [];
+    let resolved = 0;
+    let scanned = 0;
+
+    for (const file of shipped) {
+      if (!/\.(mjs|cjs|js)$/.test(file)) continue;
+      let src;
+      try {
+        src = readFileSync(resolve(root, file), "utf-8");
+      } catch {
+        continue;
+      }
+      scanned++;
+      for (const spec of extractSpecifiers(src)) {
+        if (!spec.startsWith(".")) continue; // bare and node: specifiers are not ours to resolve
+        resolved++;
+        const target = relative(root, resolve(dirname(resolve(root, file)), spec)).split(sep).join("/");
+        if (!shipped.has(target)) {
+          broken.push(`${file} imports ${spec} — ${target} is not in the tarball (on disk: ${existsSync(resolve(root, target)) ? "yes" : "no"})`);
+        }
+      }
+    }
+
+    add(
+      "tarball: every relative import resolves",
+      broken.length === 0,
+      broken.length ? broken.join("; ") : `${resolved} relative imports across ${scanned} shipped modules`
+    );
+    // A resolver that resolved nothing would report the same clean line.
+    add("tarball: the graph was actually walked", resolved > 0 && scanned > 0, `${scanned} modules, ${resolved} relative imports`);
+  }
+
+  // --- 4. Every advertised entry point has to be in the box ------------------
+  {
+    const pkg = JSON.parse(readFileSync(resolve(root, "package.json"), "utf-8"));
+    const entries = [...Object.values(pkg.bin || {}), pkg.main, pkg.module].filter(Boolean);
+    const missing = entries.map((e) => e.replace(/^\.\//, "")).filter((e) => !shipped.has(e));
+    add("entry points: every bin and main ships", missing.length === 0, missing.length ? missing.join(", ") : `${entries.length} entry points present`);
+  }
+
+  return { ok: failures.length === 0, checks, failures };
+}
+
+const isMain = process.argv[1] && process.argv[1].endsWith("package-integrity-check.mjs");
+if (isMain) {
+  const { ok, checks: rows, failures: bad } = checkPackageIntegrity();
+  if (process.argv.includes("--json")) {
+    console.log(JSON.stringify({ ok, checks: rows }, null, 2));
+  } else {
+    console.log("\n📦 Package Integrity Check (what we actually publish)");
+    console.log("-------------------------------------------------------");
+    for (const c of rows) console.log(`  ${c.ok ? "✅" : "❌"} ${c.name.padEnd(46)} ${c.detail}`);
+    console.log("-------------------------------------------------------");
+    console.log(
+      ok
+        ? "✅ The published package is self-contained.\n"
+        : `\n❌ ${bad.length} problem(s). The tarball is not what the source tree looks like.\n`
+    );
+  }
+  process.exit(ok ? 0 : 1);
+}

package/scripts/release.mjs

@@ -58,6 +58,22 @@ try {
   process.exit(1);
 }
 
+// Step 1a proved the guards work here. Here is not where users run them.
+//
+// Every signal so far was measured in the source tree, where every file
+// exists by construction. What ships is a tarball built from the `files`
+// list, and v0.63.0 published the guard-reach check without the policy
+// contract it imports — green suite, green matrix, green release, and a
+// module that threw ERR_MODULE_NOT_FOUND the moment anyone installed it.
+console.log("1a-2. Verifying the package we would publish is self-contained...");
+try {
+  execSync("node scripts/package-integrity-check.mjs", { cwd: root, stdio: "inherit" });
+  console.log("");
+} catch (_) {
+  console.error("\n❌ Release Aborted: the tarball is not what the source tree looks like.");
+  process.exit(1);
+}
+
 // 1b. Documentation / version consistency gate (blocking).
 console.log("1b. Verifying documentation is in sync with package.json & test suite...");
 {

package/src/assertions.mjs

@@ -561,12 +561,28 @@ export function assertTestIntegrity(config = {}, root = process.cwd()) {
   const res = checkTestTampering(diffStr, config);
   const diagnostics = (res.violations || []).map((v) => v.reason);
 
+  // A clean result from a guard that could not read the dialect is not a
+  // clean result, and it must not be reported as one. This does not fail the
+  // check — an unlisted assertion library is the user's normal, not their
+  // fault — but they get to know the guard is not covering them.
+  for (const u of res.unreadable || []) {
+    diagnostics.push(
+      `Test Tamper Guard: ${u.count} assertion-shaped line(s) in ${u.file} matched no known dialect, ` +
+        `so this file was not checked for tampering (e.g. ${JSON.stringify(u.samples[0])}). ` +
+        `The guard reports what it could not read rather than passing silently.`
+    );
+  }
+
   return {
     ok: res.ok,
     violations: res.violations || [],
     diagnostics,
     metrics: {
       violationCount: res.violations?.length || 0,
+      assertionsSeen: res.assertionsSeen ?? 0,
+      filesSeen: res.filesSeen ?? 0,
+      unreadableFiles: (res.unreadable || []).length,
+      status: res.status,
     },
   };
 }

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");