jules-orchestrator-kit 0.25.1 → 0.26.0

package/README.md

@@ -15,6 +15,14 @@
   Built specifically to execute 300+ daily agent sessions and parallel worktree swarms safely on native Node.js 20+ ESM.
 </p>
 
+<p align="center">
+  <a href="#-2-minute-quickstart">⚡ Quickstart</a> •
+  <a href="#-why-jules-orchestrator-kit">🎯 Why Kit?</a> •
+  <a href="#-system-architecture--visual-diagrams">🏛️ Architecture</a> •
+  <a href="#-cli-command-reference-agentctl">🛠️ CLI Commands</a> •
+  <a href="./EXAMPLES.md">📖 Recipes & Examples</a>
+</p>
+
 </div>
 
 ---
@@ -25,9 +33,21 @@
 
 ---
 
+## 🧭 Fast-Track Guide (Choose Your Path)
+
+| Your Goal | Recommended Starting Point |
+| :--- | :--- |
+| 🐣 **First time using Jules / AI Agents** | Follow the [2-Minute Quickstart](#-2-minute-quickstart) below — zero setup required! |
+| 🛠️ **Connecting to Claude Code, Cursor, or Antigravity** | Jump to [MCP & IDE Integration](#-5-model-context-protocol-mcp--ide-integration) |
+| ⚡ **Automating CI/CD Workflows** | See the [GitHub Actions Composite Action](#-github-actions-composite-action-githubactionssetup-jules) |
+| 📖 **Looking for copy-paste code patterns** | Browse 6 production recipes in [EXAMPLES.md](./EXAMPLES.md) |
+
+---
+
 ## ⚡ 2-Minute Quickstart
 
-> 💡 **TIP**: **New to Google Jules or agent automation?** You don't need any complex setup! `jules-orchestrator-kit` works out of the box with standard `npm test` and zero external dependencies.
+> [!TIP]
+> **New to Google Jules or agent automation?** You don't need any complex setup! `jules-orchestrator-kit` works out of the box with standard `npm test` and zero external runtime dependencies.
 
 ```bash
 # 1. Initialize orchestrator structure in your target codebase
@@ -45,7 +65,8 @@ npx agentctl gate
 npx agentctl mcp
 ```
 
-> 📖 **NOTE**: **Looking for production deployment patterns?**  
+> [!NOTE]
+> **Looking for production deployment patterns?**  
 > Check out [**EXAMPLES.md**](./EXAMPLES.md) for 6 real-world recipes (Nightly TODO Scanner, Composite CI Action, Multi-Worktree Swarms, OODA Auto-Fix, MCP IDE setup, and Specialist Rosters).
 
 ---
@@ -64,6 +85,23 @@ Whether you are dispatching your first automated coding task or managing high-th
 
 ---
 
+## 🛠️ CLI Command Reference (`agentctl`)
+
+| Command | Usage Example | Description |
+| :--- | :--- | :--- |
+| **`init`** | `npx agentctl init` | Initializes `.agent/` configuration, workflows, and task queue directory |
+| **`dispatch`** | `agentctl dispatch --title "Fix Bug" --prompt "..."` | Dispatches an autonomous task to Google Jules |
+| **`gate`** | `agentctl gate [--fix] [--base main]` | Runs 4-phase safety gatekeeper audit against workspace |
+| **`queue`** | `agentctl queue` | Processes pending task queue sequentially from `.agent/jules-queue/` |
+| **`swarm`** | `agentctl swarm` | Launches parallel multi-agent swarm in isolated git worktrees |
+| **`merge-swarm`** | `agentctl merge-swarm` | Performs 3-way structural merge on completed swarm PRs |
+| **`mcp`** | `agentctl mcp` | Starts stdio Model Context Protocol (MCP) JSON-RPC 2.0 server |
+| **`doctor`** | `agentctl doctor` | Verifies stack configuration, environment keys, and daily token budget |
+| **`scan`** | `agentctl scan` | Scans codebase for `TODO` and `FIXME` comments and generates task queue |
+| **`clean`** | `agentctl clean` | Audits and cleans up stale git worktrees, orphaned intents, locks, and temporary state files |
+
+---
+
 ## 🏛️ System Architecture & Visual Diagrams
 
 <details open>
@@ -91,7 +129,7 @@ Whether you are dispatching your first automated coding task or managing high-th
 
 </details>
 
-<details open>
+<details>
 <summary><b>🔁 2. Self-Healing OODA Loop Cycle</b></summary>
 
 <br/>
@@ -102,11 +140,12 @@ Whether you are dispatching your first automated coding task or managing high-th
 
 <br/>
 
-> 🚨 **IMPORTANT**: The OODA (Observe-Orient-Decide-Act) loop executes up to 3 repair attempts when tests fail. If the failure output oscillates deterministically without progress, the OODA engine halts repair to save API tokens and returns Exit Code 4.
+> [!IMPORTANT]
+> The OODA (Observe-Orient-Decide-Act) loop executes up to 3 repair attempts when tests fail. If the failure output oscillates deterministically without progress, the OODA engine halts repair to save API tokens and returns Exit Code 4.
 
 </details>
 
-<details open>
+<details>
 <summary><b>🛡️ 3. Zero-Trust Security Shield & 4-Phase Gate</b></summary>
 
 <br/>
@@ -126,11 +165,12 @@ Whether you are dispatching your first automated coding task or managing high-th
 5. **Prompt Guard Boundary (`src/prompt-guard.mjs`)**: `sanitizeUntrustedData` strips bidi control characters, ANSI escape sequences, zero-width unicode, and neutralizes prompt injection tags (`<|im_start|>`, `[INST]`).
 6. **MCP Stream Isolation (`src/mcp.mjs`)**: Seals `process.stdout.write` framing stream to prevent log output from corrupting JSON-RPC stdio frames.
 
-> ⚠️ **WARNING**: All security rules are fetched strictly from `origin/main` (never untrusted PR branches) to prevent prompt-injection attacks from altering security rules.
+> [!WARNING]
+> All security rules are fetched strictly from `origin/main` (never untrusted PR branches) to prevent prompt-injection attacks from altering security rules.
 
 </details>
 
-<details open>
+<details>
 <summary><b>🐝 4. Parallel Swarm Topology & Isolated Worktrees</b></summary>
 
 <br/>
@@ -141,11 +181,12 @@ Whether you are dispatching your first automated coding task or managing high-th
 
 <br/>
 
-> 📌 **NOTE**: Swarm execution spawns dedicated git worktrees for each task in parallel, isolated by VFS locks. Completed tasks are verified and merged back using 3-way AST/JSON structural merging (`agentctl swarm`).
+> [!NOTE]
+> Swarm execution spawns dedicated git worktrees for each task in parallel, isolated by VFS locks. Completed tasks are verified and merged back using 3-way AST/JSON structural merging (`agentctl swarm`).
 
 </details>
 
-<details open>
+<details>
 <summary><b>🔌 5. Model Context Protocol (MCP) & IDE Integration</b></summary>
 
 <br/>
@@ -173,7 +214,7 @@ npx agentctl mcp
 
 </details>
 
-<details open>
+<details>
 <summary><b>💳 6. Subscription Tier Presets Matrix</b></summary>
 
 <br/>
@@ -237,24 +278,12 @@ steps:
 
 ---
 
-## 🛠️ CLI Command Reference (`agentctl`)
+## 📖 Deep Reference Manuals & Technical Specs
 
-| Command | Usage Example | Description |
-| :--- | :--- | :--- |
-| **`init`** | `npx agentctl init` | Initializes `.agent/` configuration, workflows, and task queue directory |
-| **`dispatch`** | `agentctl dispatch --title "Fix Bug" --prompt "..."` | Dispatches an autonomous task to Google Jules |
-| **`gate`** | `agentctl gate [--fix] [--base main]` | Runs 4-phase safety gatekeeper audit against workspace |
-| **`queue`** | `agentctl queue` | Processes pending task queue sequentially from `.agent/jules-queue/` |
-| **`swarm`** | `agentctl swarm` | Launches parallel multi-agent swarm in isolated git worktrees |
-| **`merge-swarm`** | `agentctl merge-swarm` | Performs 3-way structural merge on completed swarm PRs |
-| **`mcp`** | `agentctl mcp` | Starts stdio Model Context Protocol (MCP) JSON-RPC 2.0 server |
-| **`doctor`** | `agentctl doctor` | Verifies stack configuration, environment keys, and daily token budget |
-| **`scan`** | `agentctl scan` | Scans codebase for `TODO` and `FIXME` comments and generates task queue |
-| **`clean`** | `agentctl clean` | Audits and cleans up stale git worktrees, orphaned intents, locks, and temporary state files |
+<details>
+<summary><b>📝 1. Configuration Reference (.agent/jules.yml)</b></summary>
 
----
-
-## 📝 Configuration Reference (`.agent/jules.yml`)
+<br/>
 
 Auto-generated by `agentctl init` at the root of your project:
 
@@ -274,9 +303,12 @@ limits:
   diffKb: 75
 ```
 
----
+</details>
 
-## 🚦 Exit Code Registry & Troubleshooting
+<details>
+<summary><b>🚦 2. Exit Code Registry & Troubleshooting Matrix</b></summary>
+
+<br/>
 
 Standardized exit codes enforced across all CLI utilities and CI pipelines:
 
@@ -294,9 +326,12 @@ Standardized exit codes enforced across all CLI utilities and CI pipelines:
 | `124` | **Execution Timeout** | Subprocess execution exceeded hard timeout limit (default 10 minutes). |
 | `188` | **ERR_UNMOCKED_NET** | Unmocked outbound HTTP/HTTPS egress intercepted by hermetic network guard. |
 
----
+</details>
+
+<details>
+<summary><b>🔐 3. Environment Variables Reference</b></summary>
 
-## 🔐 Environment Variables Reference
+<br/>
 
 | Variable | Description | Default |
 | :--- | :--- | :--- |
@@ -311,9 +346,12 @@ Standardized exit codes enforced across all CLI utilities and CI pipelines:
 | `BASE_BRANCH` | Base branch for PR Audits & Merge-Base checks | `main` |
 | `NO_COLOR` | Set to `true` to disable ANSI color output | `false` |
 
----
+</details>
 
-## 🌐 Supported Tech Stacks & Auto-Detection
+<details>
+<summary><b>🌐 4. Supported Tech Stacks & Auto-Detection Matrix</b></summary>
+
+<br/>
 
 The orchestrator automatically infers verification and build commands across ecosystems:
 
@@ -330,6 +368,8 @@ The orchestrator automatically infers verification and build commands across eco
 | **Elixir / Ruby** | `mix.exs` / `Gemfile` | `mix test` / `rake test` | *(standard build)* |
 | **Java / C / C++** | `pom.xml` / `Makefile` | `mvn test` / `make test` | `mvn compile` / `make` |
 
+</details>
+
 ---
 
 ## 🤝 Contributing & Standards

package/bin/agentctl.mjs

@@ -3,7 +3,7 @@
 import { parseArgs } from "node:util";
 import { readFileSync, writeFileSync, existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
-import { loadConfig, resolveRoot, detectStack } from "../src/config.mjs";
+import { loadConfig, resolveRoot, detectStack, bootstrapZeroTestRepo } from "../src/config.mjs";
 import { gate, dispatch, run, isTaskFile } from "../src/engine.mjs";
 import { acquireLock, releaseLock, lockStatus, checkDailyBudget, getQueueDir, ensureDir } from "../src/state.mjs";
 import { worktreePrune } from "../src/git.mjs";
@@ -14,7 +14,7 @@ const command = args[0];
 
 function printHelp() {
   console.log(`
-🚀 agentctl v0.25.1 — Universal Agent Orchestrator & Safety Gatekeeper
+🚀 agentctl v0.26.0 — Universal Agent Orchestrator & Safety Gatekeeper
 
 Usage: agentctl <command> [options]
 
@@ -27,6 +27,7 @@ Commands:
   clean                 Clean stale branches, worktrees, locks, and ledgers
   lock <action>         Manage mutex locks (acquire | release | status | cleanup)
   doctor                Run system diagnostics and stack resolution checks
+  bootstrap             Bootstrap zero-test repository with verification oracle
   init                  Scaffold .agent/ directory and config.yml
   version               Output agentctl version
 
@@ -44,7 +45,7 @@ async function main() {
   }
 
   if (command === "version" || command === "--version" || command === "-v") {
-    console.log("agentctl v0.25.1");
+    console.log("agentctl v0.26.0");
     process.exit(0);
   }
 
@@ -240,6 +241,28 @@ async function main() {
       break;
     }
 
+    case "bootstrap": {
+      const { values } = parseArgs({
+        args: args.slice(1),
+        options: {
+          force: { type: "boolean", short: "f" },
+        },
+        allowPositionals: true,
+      });
+
+      const res = bootstrapZeroTestRepo(root, { force: values.force });
+      if (res.bootstrapped) {
+        console.log(`✅ Zero-test repo bootstrapped successfully!`);
+        console.log(`   Stack detected : ${res.stack}`);
+        console.log(`   Oracle TestCmd : ${res.testCmd}`);
+        console.log(`   Config written : ${res.configPath}`);
+      } else {
+        console.log(`ℹ️ Repository already has a verification oracle (${res.testCmd}). Use --force to overwrite.`);
+      }
+      process.exit(0);
+      break;
+    }
+
     case "init": {
       const agentDir = join(root, ".agent");
       ensureDir(agentDir);

package/package.json

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

package/src/config.mjs

@@ -185,92 +185,15 @@ export function detectPackageManager(root = process.cwd(), pkg = {}) {
   return "npm";
 }
 
+import { detectPolyglotStack, resolveWorkspaceBoundary, bootstrapZeroTestRepo } from "./stack-detector.mjs";
+
+export { detectPolyglotStack, resolveWorkspaceBoundary, bootstrapZeroTestRepo };
+
 /**
- * Autodetects verification test/build commands across 16 common tech stacks.
+ * Autodetects verification test/build commands across 24+ polyglot tech stacks.
  */
 export function detectStack(projectRoot = process.cwd()) {
-  const detectors = [
-    {
-      files: ["turbo.json"],
-      resolve: () => ({ testCmd: "npx turbo run test", buildCmd: "npx turbo run build", stack: "turbo" }),
-    },
-    {
-      files: ["pnpm-workspace.yaml"],
-      resolve: () => ({ testCmd: "pnpm -r test", buildCmd: "pnpm -r build", stack: "pnpm" }),
-    },
-    {
-      files: ["nx.json"],
-      resolve: () => ({ testCmd: "npx nx run-many -t test", buildCmd: "npx nx run-many -t build", stack: "nx" }),
-    },
-    {
-      files: ["bunfig.toml", "bun.lockb"],
-      resolve: () => ({ testCmd: "bun test", buildCmd: "bun run build", stack: "bun" }),
-    },
-    {
-      files: ["deno.json", "deno.jsonc"],
-      resolve: () => ({ testCmd: "deno test", buildCmd: "deno task build", stack: "deno" }),
-    },
-    {
-      files: ["package.json"],
-      resolve: (root) => {
-        try {
-          const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf-8"));
-          const pm = detectPackageManager(root, pkg);
-          const scripts = pkg.scripts || {};
-          let testScript = scripts.test ? `${pm} test` : "";
-          const buildScript = scripts.build ? `${pm} run build` : "";
-          return { testCmd: testScript || `${pm} test`, buildCmd: buildScript, stack: "node" };
-        } catch (_) {
-          return { testCmd: "npm test", buildCmd: "npm run build", stack: "node" };
-        }
-      },
-    },
-    {
-      files: ["Cargo.toml"],
-      resolve: () => ({ testCmd: "cargo test --workspace", buildCmd: "cargo build", stack: "cargo" }),
-    },
-    {
-      files: ["go.mod"],
-      resolve: () => ({ testCmd: "go test ./...", buildCmd: "go build ./...", stack: "go" }),
-    },
-    {
-      files: ["pyproject.toml", "requirements.txt", "setup.py"],
-      resolve: () => ({ testCmd: "pytest", buildCmd: "", stack: "python" }),
-    },
-    {
-      files: ["mix.exs"],
-      resolve: () => ({ testCmd: "mix test", buildCmd: "mix compile", stack: "mix" }),
-    },
-    {
-      files: ["Gemfile"],
-      resolve: () => ({ testCmd: "bundle exec rake test", buildCmd: "", stack: "bundler" }),
-    },
-    {
-      files: ["Package.swift"],
-      resolve: () => ({ testCmd: "swift test", buildCmd: "swift build", stack: "swift" }),
-    },
-    {
-      files: ["pom.xml"],
-      resolve: () => ({ testCmd: "mvn test", buildCmd: "mvn compile", stack: "maven" }),
-    },
-    {
-      files: ["build.gradle", "build.gradle.kts"],
-      resolve: () => ({ testCmd: "./gradlew test", buildCmd: "./gradlew assemble", stack: "gradle" }),
-    },
-    {
-      files: ["Makefile"],
-      resolve: () => ({ testCmd: "make test", buildCmd: "make build", stack: "make" }),
-    },
-  ];
-
-  for (const detector of detectors) {
-    if (detector.files.some((f) => existsSync(join(projectRoot, f)))) {
-      const res = detector.resolve(projectRoot);
-      if (res) return res;
-    }
-  }
-
-  return { testCmd: "", buildCmd: "", stack: "unknown" };
+  return detectPolyglotStack(projectRoot);
 }
 
 export function resolveVerify(root = process.cwd()) {

package/src/merge-blocks.mjs

@@ -10,7 +10,47 @@ function sha1(content) {
 }
 
 /**
- * Chunks source code text into declaration blocks bounded by column-0 declaration boundaries.
+ * Recursively sorts object keys alphabetically to produce a canonical representation.
+ */
+function sortKeysRecursive(obj) {
+  if (obj === null || typeof obj !== "object") {
+    return obj;
+  }
+  if (Array.isArray(obj)) {
+    return obj.map(sortKeysRecursive);
+  }
+  const sorted = {};
+  const keys = Object.keys(obj).sort();
+  for (const key of keys) {
+    sorted[key] = sortKeysRecursive(obj[key]);
+  }
+  return sorted;
+}
+
+/**
+ * Computes canonical SHA-256 fingerprint for cross-language API contracts (OpenAPI/JSON/YAML).
+ */
+export function hashCrossLanguageInterface(taskId, outputFile, content = "", schemaType = "json") {
+  let cleaned = content;
+  // Strip single-line comments
+  cleaned = cleaned.replace(/^\s*\/\/.*$/gm, "").replace(/^\s*#.*$/gm, "");
+
+  let canonicalStr = cleaned.trim();
+  try {
+    const parsed = JSON.parse(cleaned);
+    const sorted = sortKeysRecursive(parsed);
+    canonicalStr = JSON.stringify(sorted);
+  } catch (_) {
+    // Fallback to normalized trimmed string if not JSON
+  }
+
+  const sha256 = createHash("sha256").update(canonicalStr).digest("hex");
+  return `${taskId}:${outputFile}:${sha256}`;
+}
+
+/**
+ * Chunks source code text into declaration blocks bounded by syntax declaration boundaries.
+ * Supports JS/TS/braced languages, Python whitespace, and XML/tag-based structures (.csproj).
  * @param {string} text
  * @param {string} [lang="js"]
  * @returns {Array<Object>} Array of block descriptors
@@ -24,11 +64,14 @@ export function chunkBlocks(text = "", lang = "js") {
   const blocks = [];
   const nameCounts = new Map();
 
-  const isPython = lang === "py" || lang === "python";
+  const isPython = lang === "py" || lang === "python" || lang === "yaml" || lang === "yml";
+  const isXml = lang === "xml" || lang === "html" || lang === "csproj" || lang === "fsproj" || lang === "vbproj" || lang === "xaml";
 
-  // Declaration regex matching column 0
-  const declRegex = /^(?:export\s+)?(?:async\s+)?(function\*?|class|const|let|var|def|type|interface|enum)\s+([a-zA-Z0-9_$]+)/;
-  const declAnyRegex = /^(?:export\s+)?(?:async\s+)?(function\*?|class|const|let|var|def|type|interface|enum)\b/;
+  // Declaration regexes matching column 0
+  const declRegex = /^(?:export\s+)?(?:async\s+)?(function\*?|class|const|let|var|def|type|interface|enum|struct|fn|pub|func)\s+([a-zA-Z0-9_$]+)/;
+  const declAnyRegex = /^(?:export\s+)?(?:async\s+)?(function\*?|class|const|let|var|def|type|interface|enum|struct|fn|pub|func)\b/;
+  const xmlTagOpenRegex = /^\s*<([a-zA-Z0-9_$-]+)(?:\s+[^>]*)?>/;
+  const xmlTagCloseRegex = /^\s*<\/([a-zA-Z0-9_$-]+)>/;
 
   let currentLines = [];
   let currentType = "prelude";
@@ -36,6 +79,7 @@ export function chunkBlocks(text = "", lang = "js") {
   let inBlock = false;
   let braceDepth = 0;
   let blockIndentLevel = 0;
+  let xmlTagName = null;
 
   function flushBlock() {
     if (currentLines.length === 0) return;
@@ -70,14 +114,37 @@ export function chunkBlocks(text = "", lang = "js") {
     inBlock = false;
     braceDepth = 0;
     blockIndentLevel = 0;
+    xmlTagName = null;
   }
 
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
     const isColumnZero = line.length > 0 && line[0] !== " " && line[0] !== "\t";
 
+    if (isXml) {
+      // XML / Tag-based chunking (.csproj, XML, HTML)
+      const openMatch = line.match(xmlTagOpenRegex);
+      const closeMatch = line.match(xmlTagCloseRegex);
+
+      if (!inBlock && openMatch && !line.includes("/>") && !openMatch[1].startsWith("?") && !openMatch[1].startsWith("!")) {
+        const tag = openMatch[1];
+        if (tag !== "Project" && tag !== "html" && tag !== "svg") {
+          flushBlock();
+          currentType = "tag";
+          currentName = tag;
+          xmlTagName = tag;
+          inBlock = true;
+        }
+      }
+      currentLines.push(line);
+      if (inBlock && closeMatch && closeMatch[1] === xmlTagName) {
+        flushBlock();
+      }
+      continue;
+    }
+
     if (isPython) {
-      // Python block logic
+      // Python & YAML whitespace block logic
       if (isColumnZero && declAnyRegex.test(line)) {
         flushBlock();
         const match = line.match(declRegex);
@@ -86,11 +153,11 @@ export function chunkBlocks(text = "", lang = "js") {
         inBlock = true;
         blockIndentLevel = 0;
       } else if (inBlock && isColumnZero && line.trim().length > 0 && !line.trim().startsWith("#")) {
-        // Dedented back to column 0 in Python
+        // Dedented back to column 0 in Python/YAML
         flushBlock();
       }
     } else {
-      // JS/TS block logic
+      // Braced syntax block logic (JS, TS, C#, Rust, Go, Swift, C/C++)
       if (isColumnZero && declAnyRegex.test(line)) {
         flushBlock();
         const match = line.match(declRegex);
@@ -103,8 +170,8 @@ export function chunkBlocks(text = "", lang = "js") {
 
     currentLines.push(line);
 
-    if (!isPython && inBlock) {
-      // Track curly brace balance for JS/TS
+    if (!isPython && !isXml && inBlock) {
+      // Track curly brace balance
       for (const char of line) {
         if (char === "{") braceDepth++;
         if (char === "}") braceDepth--;
@@ -155,25 +222,20 @@ export function mergeBlocks3Way(baseText = "", oursText = "", theirsText = "", l
 
     if (tBlock && bBlock) {
       if (oBlock.hash === tBlock.hash) {
-        // Both match exactly
         classifications.push({ id, type: "IDENTICAL" });
         outputBlocks.push(oBlock.content);
       } else if (oBlock.hash === bBlock.hash) {
-        // Ours didn't change, theirs changed
         classifications.push({ id, type: "ONLY_THEIRS" });
         outputBlocks.push(tBlock.content);
       } else if (tBlock.hash === bBlock.hash) {
-        // Theirs didn't change, ours changed
         classifications.push({ id, type: "ONLY_OURS" });
         outputBlocks.push(oBlock.content);
       } else {
-        // Both changed differently
         conflicts++;
         classifications.push({ id, type: "CONFLICT_EDIT_EDIT" });
         outputBlocks.push(`<<<<<<< OURS\n${oBlock.content}\n=======\n${tBlock.content}\n>>>>>>> THEIRS`);
       }
     } else if (tBlock && !bBlock) {
-      // Added in both ours and theirs
       if (oBlock.hash === tBlock.hash) {
         classifications.push({ id, type: "IDENTICAL" });
         outputBlocks.push(oBlock.content);
@@ -183,18 +245,14 @@ export function mergeBlocks3Way(baseText = "", oursText = "", theirsText = "", l
         outputBlocks.push(`<<<<<<< OURS\n${oBlock.content}\n=======\n${tBlock.content}\n>>>>>>> THEIRS`);
       }
     } else if (!tBlock && bBlock) {
-      // Present in base and ours, missing in theirs
       if (oBlock.hash === bBlock.hash) {
-        // Deleted by theirs, unchanged by ours
         classifications.push({ id, type: "DELETED" });
       } else {
-        // Modified by ours, deleted by theirs -> CONFLICT
         conflicts++;
         classifications.push({ id, type: "CONFLICT_EDIT_EDIT" });
         outputBlocks.push(`<<<<<<< OURS\n${oBlock.content}\n=======\n>>>>>>> THEIRS`);
       }
     } else {
-      // !tBlock && !bBlock -> ADDED_OURS
       classifications.push({ id, type: "ADDED_OURS" });
       outputBlocks.push(oBlock.content);
     }
@@ -208,16 +266,12 @@ export function mergeBlocks3Way(baseText = "", oursText = "", theirsText = "", l
 
     const bBlock = baseMap.get(id);
     if (!bBlock) {
-      // Added in theirs
       classifications.push({ id, type: "ADDED_THEIRS" });
       outputBlocks.push(tBlock.content);
     } else {
-      // Present in base and theirs, deleted by ours
       if (tBlock.hash === bBlock.hash) {
-        // Deleted by ours, unchanged by theirs
         classifications.push({ id, type: "DELETED" });
       } else {
-        // Modified by theirs, deleted by ours -> CONFLICT
         conflicts++;
         classifications.push({ id, type: "CONFLICT_EDIT_EDIT" });
         outputBlocks.push(`<<<<<<< OURS\n=======\n${tBlock.content}\n>>>>>>> THEIRS`);

package/src/stack-detector.mjs

@@ -0,0 +1,285 @@
+import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync } from "node:fs";
+import { join, sep } from "node:path";
+
+/**
+ * Generate a zero-dependency smoke test file using node:test for untested JS/Generic repos.
+ */
+export function generateSmokeTestScript(root = process.cwd()) {
+  const agentDir = join(root, ".agent");
+  try {
+    mkdirSync(agentDir, { recursive: true });
+  } catch (_) {}
+
+  const smokePath = join(agentDir, "smoke.test.mjs");
+  const content = `// Auto-generated zero-dependency smoke test gate (.agent/smoke.test.mjs)
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+
+test("Zero-Test Bootstrapped Smoke Verification", () => {
+  assert.ok(fs.existsSync(process.cwd()), "Working directory exists and is accessible");
+  const entries = fs.readdirSync(process.cwd());
+  assert.ok(entries.length > 0, "Repository contains files");
+});
+`;
+  writeFileSync(smokePath, content, "utf-8");
+  return ".agent/smoke.test.mjs";
+}
+
+/**
+ * Detects 24+ polyglot stacks and container environments.
+ */
+export function detectPolyglotStack(projectRoot = process.cwd()) {
+  const isDevcontainer = existsSync(join(projectRoot, ".devcontainer", "devcontainer.json"));
+  const isCompose =
+    existsSync(join(projectRoot, "docker-compose.yml")) ||
+    existsSync(join(projectRoot, "docker-compose.yaml")) ||
+    existsSync(join(projectRoot, "compose.yml")) ||
+    existsSync(join(projectRoot, "compose.yaml"));
+
+  const container = {
+    containerized: isDevcontainer || isCompose,
+    containerType: isDevcontainer ? "devcontainer" : isCompose ? "docker-compose" : null,
+    containerCmd: isDevcontainer
+      ? "devcontainer exec --workspace-folder ."
+      : isCompose
+      ? "docker compose exec -T app"
+      : "",
+  };
+
+  // 1. Turborepo / pnpm / Nx Monorepo workspaces
+  if (existsSync(join(projectRoot, "turbo.json"))) {
+    return { ...container, stack: "turbo", testCmd: "npx turbo run test", buildCmd: "npx turbo run build", triggerFile: "turbo.json" };
+  }
+  if (existsSync(join(projectRoot, "pnpm-workspace.yaml"))) {
+    return { ...container, stack: "pnpm", testCmd: "pnpm -r test", buildCmd: "pnpm -r build", triggerFile: "pnpm-workspace.yaml" };
+  }
+  if (existsSync(join(projectRoot, "nx.json"))) {
+    return { ...container, stack: "nx", testCmd: "npx nx run-many -t test", buildCmd: "npx nx run-many -t build", triggerFile: "nx.json" };
+  }
+
+  // 2. PHP / Laravel / WordPress
+  if (existsSync(join(projectRoot, "artisan"))) {
+    const hasPest = existsSync(join(projectRoot, "pest.php")) || existsSync(join(projectRoot, "vendor", "bin", "pest"));
+    const testCmd = hasPest ? "./vendor/bin/pest" : "./vendor/bin/phpunit";
+    return { ...container, stack: "laravel", testCmd, buildCmd: "composer dump-autoload", triggerFile: "artisan" };
+  }
+  if (existsSync(join(projectRoot, "wp-cli.yml")) || existsSync(join(projectRoot, "wp-config.php"))) {
+    return { ...container, stack: "wordpress", testCmd: "./vendor/bin/phpunit", buildCmd: "wp dist-archive", triggerFile: existsSync(join(projectRoot, "wp-cli.yml")) ? "wp-cli.yml" : "wp-config.php" };
+  }
+  if (existsSync(join(projectRoot, "composer.json")) || existsSync(join(projectRoot, "phpunit.xml")) || existsSync(join(projectRoot, "pest.php"))) {
+    let testCmd = "./vendor/bin/phpunit";
+    if (existsSync(join(projectRoot, "pest.php")) || existsSync(join(projectRoot, "vendor", "bin", "pest"))) {
+      testCmd = "./vendor/bin/pest";
+    } else if (existsSync(join(projectRoot, "composer.json"))) {
+      try {
+        const composer = JSON.parse(readFileSync(join(projectRoot, "composer.json"), "utf-8"));
+        if (composer.scripts && composer.scripts.test) {
+          testCmd = "composer test";
+        }
+      } catch (_) {}
+    }
+    const triggerFile = existsSync(join(projectRoot, "composer.json")) ? "composer.json" : existsSync(join(projectRoot, "pest.php")) ? "pest.php" : "phpunit.xml";
+    return { ...container, stack: "php", testCmd, buildCmd: "composer dump-autoload", triggerFile };
+  }
+
+  // 3. Mobile & Cross-Platform (pubspec.yaml, Package.swift, app.json)
+  if (existsSync(join(projectRoot, "pubspec.yaml"))) {
+    let isFlutter = false;
+    try {
+      const content = readFileSync(join(projectRoot, "pubspec.yaml"), "utf-8");
+      if (content.includes("flutter:") || content.includes("sdk: flutter")) {
+        isFlutter = true;
+      }
+    } catch (_) {}
+    if (isFlutter) {
+      return { ...container, stack: "flutter", testCmd: "flutter test", buildCmd: "flutter build apk --debug", triggerFile: "pubspec.yaml" };
+    }
+    return { ...container, stack: "dart", testCmd: "dart test", buildCmd: "dart compile exe bin/main.dart", triggerFile: "pubspec.yaml" };
+  }
+  if (existsSync(join(projectRoot, "Package.swift"))) {
+    return { ...container, stack: "swift", testCmd: "swift test", buildCmd: "swift build", triggerFile: "Package.swift" };
+  }
+  if (existsSync(join(projectRoot, "app.json")) || existsSync(join(projectRoot, "react-native.config.js"))) {
+    const triggerFile = existsSync(join(projectRoot, "app.json")) ? "app.json" : "react-native.config.js";
+    return { ...container, stack: "react-native", testCmd: "npm test", buildCmd: "npx react-native bundle --platform android --dev false --entry-file index.js --bundle-output android/main.jsbundle", triggerFile };
+  }
+
+  // 4. Systems & C/C++ / Rust / Go / Make
+  if (existsSync(join(projectRoot, "CMakeLists.txt"))) {
+    return { ...container, stack: "cmake", testCmd: "ctest --test-dir build --output-on-failure", buildCmd: "cmake --build build", triggerFile: "CMakeLists.txt" };
+  }
+  if (existsSync(join(projectRoot, "Cargo.toml"))) {
+    return { ...container, stack: "cargo", testCmd: "cargo test --workspace", buildCmd: "cargo build", triggerFile: "Cargo.toml" };
+  }
+  if (existsSync(join(projectRoot, "go.mod"))) {
+    return { ...container, stack: "go", testCmd: "go test ./...", buildCmd: "go build ./...", triggerFile: "go.mod" };
+  }
+  if (existsSync(join(projectRoot, "Makefile"))) {
+    return { ...container, stack: "make", testCmd: "make test", buildCmd: "make build", triggerFile: "Makefile" };
+  }
+
+  // 5. Python / Elixir / Ruby / Java
+  if (existsSync(join(projectRoot, "pyproject.toml")) || existsSync(join(projectRoot, "requirements.txt")) || existsSync(join(projectRoot, "setup.py"))) {
+    const triggerFile = existsSync(join(projectRoot, "pyproject.toml")) ? "pyproject.toml" : existsSync(join(projectRoot, "requirements.txt")) ? "requirements.txt" : "setup.py";
+    return { ...container, stack: "python", testCmd: "pytest", buildCmd: "python3 -m compileall -q .", triggerFile };
+  }
+  if (existsSync(join(projectRoot, "mix.exs"))) {
+    return { ...container, stack: "mix", testCmd: "mix test", buildCmd: "mix compile", triggerFile: "mix.exs" };
+  }
+  if (existsSync(join(projectRoot, "Gemfile"))) {
+    return { ...container, stack: "bundler", testCmd: "bundle exec rake test", buildCmd: "bundle exec rake build", triggerFile: "Gemfile" };
+  }
+  if (existsSync(join(projectRoot, "pom.xml"))) {
+    return { ...container, stack: "maven", testCmd: "mvn test", buildCmd: "mvn compile", triggerFile: "pom.xml" };
+  }
+  if (existsSync(join(projectRoot, "build.gradle")) || existsSync(join(projectRoot, "build.gradle.kts"))) {
+    const triggerFile = existsSync(join(projectRoot, "build.gradle")) ? "build.gradle" : "build.gradle.kts";
+    return { ...container, stack: "gradle", testCmd: "./gradlew test", buildCmd: "./gradlew assemble", triggerFile };
+  }
+
+  // 6. JS / TS Runtimes
+  if (existsSync(join(projectRoot, "bunfig.toml")) || existsSync(join(projectRoot, "bun.lockb"))) {
+    const triggerFile = existsSync(join(projectRoot, "bunfig.toml")) ? "bunfig.toml" : "bun.lockb";
+    return { ...container, stack: "bun", testCmd: "bun test", buildCmd: "bun run build", triggerFile };
+  }
+  if (existsSync(join(projectRoot, "deno.json")) || existsSync(join(projectRoot, "deno.jsonc"))) {
+    const triggerFile = existsSync(join(projectRoot, "deno.json")) ? "deno.json" : "deno.jsonc";
+    return { ...container, stack: "deno", testCmd: "deno test", buildCmd: "deno task build", triggerFile };
+  }
+  if (existsSync(join(projectRoot, "package.json"))) {
+    let testScript = "npm test";
+    let buildScript = "npm run build";
+    try {
+      const pkg = JSON.parse(readFileSync(join(projectRoot, "package.json"), "utf-8"));
+      if (pkg && typeof pkg === "object") {
+        const scripts = pkg.scripts || {};
+        testScript = scripts.test ? "npm test" : "npm test";
+        buildScript = scripts.build ? "npm run build" : "";
+      }
+    } catch (_) {
+      testScript = "npm test";
+      buildScript = "npm run build";
+    }
+    return { ...container, stack: "node", testCmd: testScript, buildCmd: buildScript, triggerFile: "package.json" };
+  }
+
+  // 7. .NET / C# / F# / PHP / Python root file extension fallback
+  try {
+    const rootFiles = readdirSync(projectRoot);
+    const slnFile = rootFiles.find((f) => f.endsWith(".sln") || f.endsWith(".csproj") || f.endsWith(".fsproj"));
+    if (slnFile) {
+      return { ...container, stack: "dotnet", testCmd: "dotnet test --no-restore --nologo", buildCmd: "dotnet build --no-incremental --nologo", triggerFile: slnFile };
+    }
+    const phpFile = rootFiles.find((f) => f.endsWith(".php"));
+    if (phpFile) {
+      return { ...container, stack: "php", testCmd: 'php -l $(find . -name "*.php" -not -path "./vendor/*" -not -path "./node_modules/*")', buildCmd: "composer dump-autoload", triggerFile: phpFile };
+    }
+    const pyFile = rootFiles.find((f) => f.endsWith(".py"));
+    if (pyFile) {
+      return { ...container, stack: "python", testCmd: "pytest", buildCmd: "python3 -m compileall -q .", triggerFile: pyFile };
+    }
+  } catch (_) {}
+
+  return { ...container, stack: "unknown", testCmd: "", buildCmd: "", triggerFile: null };
+}
+
+/**
+ * Resolves workspace boundaries in polyglot monorepos by mapping changed files to subprojects.
+ */
+export function resolveWorkspaceBoundary(changedFiles = [], root = process.cwd()) {
+  const rootStack = detectPolyglotStack(root);
+  if (!changedFiles || changedFiles.length === 0) {
+    return { isMonorepo: false, globalFallback: false, projects: [{ path: ".", ...rootStack }], testCmd: rootStack.testCmd, buildCmd: rootStack.buildCmd };
+  }
+
+  const sharedTriggers = new Set(["openapi.yaml", "openapi.json", "schema.graphql", "docker-compose.yml", "Makefile", "turbo.json", "pnpm-workspace.yaml", "nx.json"]);
+  for (const file of changedFiles) {
+    const baseName = file.split(sep).pop();
+    if (sharedTriggers.has(baseName) || file.startsWith(".agent/") || file.startsWith(".github/")) {
+      return { isMonorepo: true, globalFallback: true, projects: [{ path: ".", ...rootStack }], testCmd: rootStack.testCmd, buildCmd: rootStack.buildCmd };
+    }
+  }
+
+  const projectMap = new Map();
+  for (const file of changedFiles) {
+    const parts = file.split(sep);
+    let resolved = false;
+
+    for (let i = parts.length - 1; i >= 1; i--) {
+      const subDir = parts.slice(0, i).join("/");
+      const subStack = detectPolyglotStack(join(root, subDir));
+      if (subStack.stack !== "unknown" && subStack.triggerFile) {
+        if (!projectMap.has(subDir)) {
+          projectMap.set(subDir, { path: subDir, ...subStack });
+        }
+        resolved = true;
+        break;
+      }
+    }
+
+    if (!resolved && !projectMap.has(".")) {
+      projectMap.set(".", { path: ".", ...rootStack });
+    }
+  }
+
+  const projects = Array.from(projectMap.values());
+  const testCmds = projects
+    .filter((p) => p.testCmd)
+    .map((p) => (p.path === "." ? p.testCmd : `(cd ${p.path} && ${p.testCmd})`));
+  const buildCmds = projects
+    .filter((p) => p.buildCmd)
+    .map((p) => (p.path === "." ? p.buildCmd : `(cd ${p.path} && ${p.buildCmd})`));
+
+  return {
+    isMonorepo: projects.length > 1,
+    globalFallback: false,
+    projects,
+    testCmd: testCmds.join(" && ") || rootStack.testCmd,
+    buildCmd: buildCmds.join(" && ") || rootStack.buildCmd,
+  };
+}
+
+export function bootstrapZeroTestRepo(root = process.cwd(), options = {}) {
+  const detected = detectPolyglotStack(root);
+  const configPath = join(root, ".agent", "config.yml");
+  const hasConfig = existsSync(configPath);
+  const hasRealTestSuite =
+    hasConfig ||
+    existsSync(join(root, "phpunit.xml")) ||
+    existsSync(join(root, "pest.php")) ||
+    existsSync(join(root, "turbo.json")) ||
+    existsSync(join(root, "pnpm-workspace.yaml")) ||
+    existsSync(join(root, "nx.json"));
+
+  if (!options.force && hasRealTestSuite) {
+    return { bootstrapped: false, reason: "EXISTING_VERIFICATION_ORACLE", testCmd: detected.testCmd };
+  }
+
+  let testCmd = "";
+  if (detected.stack === "php" || detected.stack === "laravel" || detected.stack === "wordpress") {
+    testCmd = 'php -l $(find . -name "*.php" -not -path "./vendor/*" -not -path "./node_modules/*")';
+  } else if (detected.stack === "python") {
+    testCmd = "python3 -m compileall -q -x '^\\./(\\.\\venv|venv|node_modules|\\.git)/' .";
+  } else if (detected.stack === "dotnet") {
+    testCmd = "dotnet build --no-incremental --nologo";
+  } else if (detected.stack === "cargo") {
+    testCmd = "cargo check --workspace --all-targets";
+  } else if (detected.stack === "go") {
+    testCmd = "go vet ./...";
+  } else if (existsSync(join(root, "tsconfig.json"))) {
+    testCmd = "npx tsc --noEmit";
+  } else {
+    const smokePath = generateSmokeTestScript(root);
+    testCmd = `node --test ${smokePath}`;
+  }
+
+  try {
+    mkdirSync(join(root, ".agent"), { recursive: true });
+  } catch (_) {}
+
+  const cfg = `version: 1\nprovider: jules\ntier: ultra\nverify:\n  test: "${testCmd}"\n  build: "${detected.buildCmd || ""}"\nlimits:\n  diff_kb: 75\n  daily_tasks: 300\n  repair_attempts: 3\nbranch_prefix: agent/\nbase_branch: main\n`;
+  writeFileSync(configPath, cfg, "utf-8");
+
+  return { bootstrapped: true, stack: detected.stack, testCmd, configPath };
+}