jules-orchestrator-kit 0.52.0 → 0.52.1

package/README.md

@@ -59,7 +59,7 @@ npx jules-orchestrator-kit init
 ```bash
 # 2. Commit what init wrote — .agent/config.yml is on the gate's deny list by
 #    design, so leaving it uncommitted makes the first gate reject your tree
-git add .agent AGENTS.md .gitignore && git commit -m "chore: add agent config"
+git add .agent AGENTS.md SPEC.md CONSTRAINTS.md .gitignore && git commit -m "chore: add agent config"
 ```
 
 ```bash
@@ -143,7 +143,7 @@ To maximize PR merge rates, dispatch tasks according to deterministic boundaries
 * **Fail-Closed Security & Secret Redaction:** Evaluates explicit Deny rules before Allow rules against canonicalized, case-folded paths. Redacts high-entropy keys and base64-encoded credentials (such as Kubernetes `Secret` manifests).
 * **Complexity & Cost Router:** Zero-dependency heuristic classifier (`src/router.mjs`) routing mechanical tasks to lightweight models while reserving primary models for complex refactors, with a `node --check` syntax-verification gate that transparently escalates a FAST-tier result to the primary provider if it left broken JS on disk.
 * **Terminal UI & Diagnostic Matrix (`agentctl doctor`):** Interactive terminal dashboard, task sidecar manager, and automated transactional self-repair.
-* **Verified Test Suite:** Tested with **797 unit tests across 91 suites passing in < 10.0s**.
+* **Verified Test Suite:** Tested with **802 unit tests across 91 suites passing in < 10.0s**.
 
 <br/>
 

package/bin/agentctl.mjs

@@ -228,9 +228,16 @@ async function main() {
     process.exit(0);
   }
 
-  // Intercept --help / -h on any subcommand (e.g. `agentctl init --help`)
+  // Resolve --help / -h on subcommands (e.g. `agentctl init --help`, `agentctl mutate --help`)
   const subArgs = args.slice(1);
   if (subArgs.includes("--help") || subArgs.includes("-h")) {
+    const { getCommandDescriptor, formatCommandHelp } = await import("../src/ops/command-registry.mjs");
+    const subSub = subArgs[0] && !subArgs[0].startsWith("-") ? `${command} ${subArgs[0]}` : command;
+    const desc = getCommandDescriptor(subSub) || getCommandDescriptor(command);
+    if (desc) {
+      console.log(formatCommandHelp(desc));
+      process.exit(0);
+    }
     printHelp();
     process.exit(0);
   }
@@ -1236,6 +1243,9 @@ async function main() {
         args: args.slice(1),
         options: {
           interactive: { type: "boolean", short: "i" },
+          "non-interactive": { type: "boolean" },
+          "no-interactive": { type: "boolean" },
+          yes: { type: "boolean", short: "y" },
           tier: { type: "string", short: "t" },
           json: { type: "boolean", short: "j" },
           "dry-run": { type: "boolean", short: "d" },
@@ -1244,9 +1254,11 @@ async function main() {
         allowPositionals: true,
       });
 
+      const isInteractive = values.interactive !== false && !values["non-interactive"] && !values["no-interactive"] && !values.yes;
+
       const { runInitWizard } = await import("../src/wizard-init.mjs");
       const res = await runInitWizard(root, {
-        interactive: values.interactive !== false,
+        interactive: isInteractive,
         // No `|| "pro"`: a hardcoded default here overrode both the tier picked
         // in the menu and the tier already recorded in .agent/config.yml on a
         // re-run. Undefined lets the wizard seed the menu from the existing
@@ -1267,7 +1279,11 @@ async function main() {
       } else {
         console.log(`✅ Onboarding complete! Manifest generated at ${res.configPath}`);
         console.log(`   Tier: ${res.plan.tier.toUpperCase()} (${res.plan.limits.concurrency} worker(s), ${res.plan.limits.daily_tasks} daily tasks)`);
-        console.log(`   Verification Test Command : "${res.plan.verify.test}"`);
+        if (res.plan.verify.test) {
+          console.log(`   Verification Test Command : "${res.plan.verify.test}"`);
+        } else {
+          console.log(`   Verification Test Command : None detected (run "agentctl bootstrap" to create a test oracle)`);
+        }
         console.log(`   Active Presets            : ${res.plan.presets.join(", ")}`);
         for (const item of scaffold.created) {
           console.log(`   Scaffolded                : ${item}`);
@@ -1281,8 +1297,10 @@ async function main() {
         // uncommitted meant the very first `agentctl gate` rejected the working
         // tree for files init had just written, which reads as the tool
         // catching the user cheating on step three.
-        console.log(`\n   Commit the manifest so the gate does not read it as an agent edit:`);
-        console.log(`     git add .agent AGENTS.md .gitignore && git commit -m "chore: add agent config"`);
+        const rootContracts = ["SPEC.md", "CONSTRAINTS.md", "DESIGN.md"].filter((f) => existsSync(join(root, f)));
+        const filesToAdd = [".agent", "AGENTS.md", ...rootContracts, ".gitignore"].filter((f) => existsSync(join(root, f)));
+        console.log(`\n   Commit the manifest and contracts so the gate does not read them as agent edits:`);
+        console.log(`     git add ${filesToAdd.join(" ")} && git commit -m "chore: add agent config"`);
 
         const { resolveNextStep, renderNextStep } = await import("../src/ops/next-step.mjs");
         const next = resolveNextStep(root);
@@ -1310,12 +1328,19 @@ async function main() {
             "auto-pr": { type: "boolean" },
             "require-plan-approval": { type: "boolean" },
             repoless: { type: "boolean" },
+            interactive: { type: "boolean", short: "i" },
+            "non-interactive": { type: "boolean" },
+            "no-interactive": { type: "boolean" },
+            yes: { type: "boolean", short: "y" },
             json: { type: "boolean", short: "j" },
             "dry-run": { type: "boolean", short: "d" },
           },
           allowPositionals: true,
         });
 
+        const isNonInteractive = Boolean(values["non-interactive"] || values["no-interactive"] || values.yes);
+        const isInteractive = values.interactive === true ? true : (isNonInteractive ? false : undefined);
+
         const { runTaskCreateWizard } = await import("../src/wizard-task.mjs");
         const res = await runTaskCreateWizard(root, {
           title: values.title,
@@ -1328,6 +1353,7 @@ async function main() {
           autoPr: values["auto-pr"],
           requirePlanApproval: values["require-plan-approval"],
           repoless: values.repoless,
+          interactive: isInteractive,
         });
 
         if (values.json) {
@@ -1475,7 +1501,7 @@ async function main() {
       const todos = scanCodebaseForTodos(root);
       console.log(`\n🔍 Scanned ${todos.length} TODO/FIXME annotation(s).`);
       for (const t of todos.slice(0, 10)) {
-        console.log(`   - ${t.file}:${t.line} [${t.type}] ${t.text}`);
+        console.log(`   - ${t.file}:${t.line} [${t.type || t.tag || "TODO"}] ${t.text}`);
       }
       if (todos.length > 10) {
         console.log(`   ... and ${todos.length - 10} more.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jules-orchestrator-kit",
-  "version": "0.52.0",
+  "version": "0.52.1",
   "description": "Zero-dependency safety gatekeeper, test oracle generator, and multi-agent coordination protocol for Google Jules (jules) autonomous agents.",
   "repository": {
     "type": "git",

package/scripts/jules-scan-todos.mjs

@@ -24,9 +24,9 @@ export function scanCodebaseForTodos(dir = process.cwd()) {
           const lines = content.split("\n");
           lines.forEach((line, idx) => {
             if (line.includes("TODO:")) {
-              todos.push({ file: full, line: idx + 1, text: line.trim(), tag: "TODO", priority: "MEDIUM" });
+              todos.push({ file: full, line: idx + 1, text: line.trim(), tag: "TODO", type: "TODO", priority: "MEDIUM" });
             } else if (line.includes("FIXME:")) {
-              todos.push({ file: full, line: idx + 1, text: line.trim(), tag: "FIXME", priority: "HIGH" });
+              todos.push({ file: full, line: idx + 1, text: line.trim(), tag: "FIXME", type: "FIXME", priority: "HIGH" });
             }
           });
         }

package/src/ops/command-registry.mjs

@@ -141,10 +141,23 @@ export const COMMAND_REGISTRY = [
       "agentctl task create --interactive",
     ],
     flags: [
-      { name: "title", type: "string", description: "Short title for task" },
-      { name: "prompt", type: "string", description: "Detailed task instructions" },
-      { name: "verify-cmd", type: "string", description: "Verification command" },
-      { name: "interactive", type: "boolean", description: "Launch interactive task wizard" },
+      { name: "title", type: "string", description: "Short title for task (-t)" },
+      { name: "prompt", type: "string", description: "Detailed task instructions (-p)" },
+      { name: "prompt-file", type: "string", description: "Read prompt from file (-f)" },
+      { name: "role", type: "string", description: "Specialist role (overseer, bolt, sentinel, janitor, a11y, scribe, spectator, alchemist) (-r)" },
+      { name: "tier", type: "string", description: "Execution tier override (fast | complex)" },
+      { name: "template", type: "string", description: "Task template preset ID" },
+      { name: "depends-on", type: "string", description: "Comma-separated task dependency IDs" },
+      { name: "verify-cmd", type: "string", description: "Verification command override (-v)" },
+      { name: "auto-pr", type: "boolean", description: "Automatically create GitHub PR upon completion" },
+      { name: "require-plan-approval", type: "boolean", description: "Require approval of agent plan before execution" },
+      { name: "repoless", type: "boolean", description: "Execute in repoless sandbox mode" },
+      { name: "interactive", type: "boolean", description: "Launch interactive task wizard (-i)" },
+      { name: "non-interactive", type: "boolean", description: "Bypass interactive prompts and use CLI flags" },
+      { name: "no-interactive", type: "boolean", description: "Alias for --non-interactive" },
+      { name: "yes", type: "boolean", description: "Accept default values non-interactively (-y)" },
+      { name: "dry-run", type: "boolean", description: "Simulate task envelope creation without queueing (-d)" },
+      { name: "json", type: "boolean", description: "Output structured JSON envelope (-j)" },
     ],
   },
   {
@@ -187,9 +200,14 @@ export const COMMAND_REGISTRY = [
       "agentctl init --tier pro --yes",
     ],
     flags: [
-      { name: "tier", type: "string", description: "Target configuration tier (free, pro, ultra, enterprise)" },
-      { name: "interactive", type: "boolean", description: "Launch interactive onboarding wizard" },
-      { name: "yes", type: "boolean", description: "Accept auto-detected Stack Oracle defaults" },
+      { name: "tier", type: "string", description: "Target configuration tier (free, pro, ultra, enterprise) (-t)" },
+      { name: "interactive", type: "boolean", description: "Launch interactive onboarding wizard (-i)" },
+      { name: "non-interactive", type: "boolean", description: "Run non-interactively with defaults" },
+      { name: "no-interactive", type: "boolean", description: "Alias for --non-interactive" },
+      { name: "yes", type: "boolean", description: "Accept auto-detected Stack Oracle defaults (-y)" },
+      { name: "force", type: "boolean", description: "Force overwrite existing config and assets (-f)" },
+      { name: "dry-run", type: "boolean", description: "Preview plan without writing files (-d)" },
+      { name: "json", type: "boolean", description: "Output structured JSON manifest (-j)" },
     ],
   },
   {
@@ -333,6 +351,185 @@ export const COMMAND_REGISTRY = [
       { name: "limit", type: "string", description: "Maximum handovers to list" },
     ],
   },
+  {
+    id: "mutate",
+    path: ["mutate"],
+    title: "mutate",
+    description: "Run zero-dependency diff mutation testing harness",
+    category: "Inspect",
+    mutates: false,
+    risk: "low",
+    interactive: "never",
+    requiresRepository: true,
+    shortcuts: ["mutation"],
+    examples: [
+      "agentctl mutate",
+      "agentctl mutate --min-score 80",
+      'agentctl mutate --max-mutants 20 --test-cmd "npm test"',
+    ],
+    flags: [
+      { name: "min-score", type: "string", description: "Target minimum mutation score threshold (0-100)" },
+      { name: "max-mutants", type: "string", description: "Maximum number of mutants to generate and test" },
+      { name: "test-cmd", type: "string", description: "Test command override" },
+      { name: "verify-cmd", type: "string", description: "Alias for test-cmd" },
+      { name: "tier", type: "string", description: "Execution tier (fast | complex)" },
+      { name: "dry-run", type: "boolean", description: "Simulate mutation analysis without executing tests (-d)" },
+      { name: "json", type: "boolean", description: "Output structured JSON mutation report (-j)" },
+    ],
+  },
+  {
+    id: "coverage",
+    path: ["coverage"],
+    title: "coverage",
+    description: "Run native zero-dependency V8 diff coverage check",
+    category: "Inspect",
+    mutates: false,
+    risk: "low",
+    interactive: "never",
+    requiresRepository: true,
+    shortcuts: ["cov"],
+    examples: [
+      "agentctl coverage",
+      "agentctl coverage --min 80",
+      'agentctl coverage --cmd "node --test"',
+    ],
+    flags: [
+      { name: "min", type: "string", description: "Minimum diff line coverage percentage required" },
+      { name: "cmd", type: "string", description: "Test command override to run with V8 coverage" },
+      { name: "test-cmd", type: "string", description: "Alias for cmd" },
+      { name: "verify-cmd", type: "string", description: "Alias for cmd" },
+      { name: "dry-run", type: "boolean", description: "Simulate coverage collection without running (-d)" },
+      { name: "json", type: "boolean", description: "Output structured JSON coverage report (-j)" },
+    ],
+  },
+  {
+    id: "gate",
+    path: ["gate"],
+    title: "gate",
+    description: "Run CI security, rules, and stack verification gate",
+    category: "Inspect",
+    mutates: false,
+    risk: "low",
+    interactive: "never",
+    requiresRepository: true,
+    shortcuts: ["audit", "check"],
+    examples: [
+      "agentctl gate",
+      "agentctl gate --mode working-tree",
+      "agentctl gate --fix",
+      "agentctl gate --json",
+    ],
+    flags: [
+      { name: "mode", type: "string", description: "Evaluation mode (working-tree | committed | staged) (-m)" },
+      { name: "tier", type: "string", description: "Enforce specific tier policies (free | pro | ultra | enterprise)" },
+      { name: "allow-protected", type: "boolean", description: "Bypass protected path checks for authorized maintainers" },
+      { name: "fix", type: "boolean", description: "Trigger automated OODA self-repair loop on failure" },
+      { name: "strict-locks", type: "boolean", description: "Enforce strict anti-tampering verification on test files" },
+      { name: "dry-run", type: "boolean", description: "Simulate gate evaluation without persisting evidence (-d)" },
+      { name: "json", type: "boolean", description: "Output structured JSON gate report (-j)" },
+    ],
+  },
+  {
+    id: "probe",
+    path: ["probe"],
+    title: "probe",
+    description: "Run test flakiness stability probe across N repetitions",
+    category: "Inspect",
+    mutates: false,
+    risk: "low",
+    interactive: "never",
+    requiresRepository: true,
+    shortcuts: ["stability"],
+    examples: [
+      "agentctl probe",
+      "agentctl probe --repeat 10",
+      'agentctl probe --repeat 5 --cmd "pytest"',
+    ],
+    flags: [
+      { name: "repeat", type: "string", description: "Number of probe executions (default: 5)" },
+      { name: "cmd", type: "string", description: "Test command to probe" },
+      { name: "test-cmd", type: "string", description: "Alias for cmd" },
+      { name: "verify-cmd", type: "string", description: "Alias for cmd" },
+      { name: "dry-run", type: "boolean", description: "Preview probe plan without execution (-d)" },
+      { name: "json", type: "boolean", description: "Output structured JSON probe telemetry (-j)" },
+    ],
+  },
+  {
+    id: "perf",
+    path: ["perf"],
+    title: "perf",
+    description: "Monitor Node.js event loop delay and Big-O performance lag",
+    category: "Inspect",
+    mutates: false,
+    risk: "low",
+    interactive: "never",
+    requiresRepository: true,
+    shortcuts: ["event-loop"],
+    examples: [
+      "agentctl perf",
+      'agentctl perf --max-ms 50 --cmd "npm test"',
+    ],
+    flags: [
+      { name: "max-ms", type: "string", description: "Maximum allowable event loop delay threshold in ms" },
+      { name: "cmd", type: "string", description: "Command to execute during performance monitoring" },
+      { name: "test-cmd", type: "string", description: "Alias for cmd" },
+      { name: "verify-cmd", type: "string", description: "Alias for cmd" },
+      { name: "dry-run", type: "boolean", description: "Preview performance monitoring configuration (-d)" },
+      { name: "json", type: "boolean", description: "Output structured JSON performance report (-j)" },
+    ],
+  },
+  {
+    id: "dispatch",
+    path: ["dispatch"],
+    title: "dispatch",
+    description: "Dispatch a single task to an AI agent",
+    category: "Operate",
+    mutates: true,
+    risk: "moderate",
+    interactive: "never",
+    requiresRepository: true,
+    shortcuts: ["create"],
+    examples: [
+      'agentctl dispatch --prompt "Add retry handling to src/webhook.js"',
+      'agentctl dispatch -p "Fix type errors" --role bolt --tier fast',
+      'agentctl dispatch --prompt-file task.md --dry-run',
+    ],
+    flags: [
+      { name: "prompt", type: "string", description: "Task prompt instructions (-p)" },
+      { name: "prompt-file", type: "string", description: "Read prompt from file (-f)" },
+      { name: "role", type: "string", description: "Specialist role (overseer, bolt, sentinel, janitor, a11y, scribe, spectator, alchemist) (-r)" },
+      { name: "tier", type: "string", description: "Execution tier override (fast | complex)" },
+      { name: "check-premise", type: "boolean", description: "Verify premise locally before dispatching" },
+      { name: "source", type: "string", description: "Jules repository source identifier (-s)" },
+      { name: "branch", type: "string", description: "Starting branch for task execution (-b)" },
+      { name: "repoless", type: "boolean", description: "Dispatch task in repoless execution mode" },
+      { name: "auto-pr", type: "boolean", description: "Automatically create PR upon completion" },
+      { name: "require-plan-approval", type: "boolean", description: "Require human approval for proposed plan" },
+      { name: "dry-run", type: "boolean", description: "Simulate dispatch without sending to provider (-d)" },
+      { name: "json", type: "boolean", description: "Output JSON structured dispatch result (-j)" },
+    ],
+  },
+  {
+    id: "bootstrap",
+    path: ["bootstrap"],
+    title: "bootstrap",
+    description: "Bootstrap zero-test repository with verification oracle",
+    category: "Configure",
+    mutates: true,
+    risk: "moderate",
+    interactive: "never",
+    requiresRepository: true,
+    shortcuts: ["bs"],
+    examples: [
+      "agentctl bootstrap",
+      "agentctl bootstrap --force",
+    ],
+    flags: [
+      { name: "force", type: "boolean", description: "Overwrite existing verification oracle or config (-f)" },
+      { name: "dry-run", type: "boolean", description: "Simulate bootstrap without writing files (-d)" },
+      { name: "json", type: "boolean", description: "Output JSON structured bootstrap result (-j)" },
+    ],
+  },
 ];
 
 /**

package/src/ops/next-step.mjs

@@ -1,6 +1,7 @@
 import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { spawnSync } from "node:child_process";
+import { isTaskFile } from "../engine.mjs";
 
 /**
  * Work out the one thing the operator should do next.
@@ -66,7 +67,7 @@ export function resolveNextStep(root, env = process.env) {
   const fallbackQueueDir = join(root, ".agent", "queue");
   const queueDir = existsSync(primaryQueueDir) ? primaryQueueDir : fallbackQueueDir;
   const queued = existsSync(queueDir)
-    ? readdirSync(queueDir).filter((f) => f.endsWith(".md") || f.endsWith(".json") || f.endsWith(".yml")).length
+    ? readdirSync(queueDir).filter((f) => isTaskFile(f, queueDir)).length
     : 0;
   if (queued > 0) {
     return {

package/src/stack-detector.mjs

@@ -210,8 +210,12 @@ export function detectPolyglotStack(projectRoot = process.cwd()) {
     setupCmd = "npx drizzle-kit push";
   }
 
-  if (existsSync(join(projectRoot, "bunfig.toml")) || existsSync(join(projectRoot, "bun.lockb"))) {
-    const triggerFile = existsSync(join(projectRoot, "bunfig.toml")) ? "bunfig.toml" : "bun.lockb";
+  if (existsSync(join(projectRoot, "bunfig.toml")) || existsSync(join(projectRoot, "bun.lockb")) || existsSync(join(projectRoot, "bun.lock"))) {
+    const triggerFile = existsSync(join(projectRoot, "bunfig.toml"))
+      ? "bunfig.toml"
+      : existsSync(join(projectRoot, "bun.lockb"))
+      ? "bun.lockb"
+      : "bun.lock";
     return { ...container, stack: "bun", setupCmd, testCmd: "bun test", buildCmd: "bun run build", triggerFile };
   }
   if (existsSync(join(projectRoot, "deno.json")) || existsSync(join(projectRoot, "deno.jsonc"))) {
@@ -219,20 +223,38 @@ export function detectPolyglotStack(projectRoot = process.cwd()) {
     return { ...container, stack: "deno", setupCmd, testCmd: "deno test", buildCmd: "deno task build", triggerFile };
   }
   if (existsSync(join(projectRoot, "package.json"))) {
-    let testScript = "npm test";
-    let buildScript = "npm run build";
+    const hasPnpm = existsSync(join(projectRoot, "pnpm-lock.yaml"));
+    const hasYarn = existsSync(join(projectRoot, "yarn.lock"));
+    const hasBun = existsSync(join(projectRoot, "bun.lock")) || existsSync(join(projectRoot, "bun.lockb"));
+    const pm = hasPnpm ? "pnpm" : hasYarn ? "yarn" : hasBun ? "bun" : "npm";
+    const triggerFile = hasPnpm
+      ? "pnpm-lock.yaml"
+      : hasYarn
+      ? "yarn.lock"
+      : hasBun
+      ? (existsSync(join(projectRoot, "bun.lock")) ? "bun.lock" : "bun.lockb")
+      : "package.json";
+
+    let testScript = "";
+    let buildScript = "";
     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" : "";
+        if (scripts.test) {
+          testScript = pm === "yarn" ? "yarn test" : `${pm} test`;
+        } else if (pm === "bun") {
+          testScript = "bun test";
+        }
+        if (scripts.build) {
+          buildScript = pm === "yarn" ? "yarn build" : `${pm} run build`;
+        }
       }
     } catch (_) {
-      testScript = "npm test";
-      buildScript = "npm run build";
+      testScript = "";
+      buildScript = "";
     }
-    return { ...container, stack: "node", setupCmd, testCmd: testScript, buildCmd: buildScript, triggerFile: "package.json" };
+    return { ...container, stack: pm === "npm" ? "node" : pm, setupCmd, testCmd: testScript, buildCmd: buildScript, triggerFile };
   }
 
   // 7. .NET / C# / F# / PHP / Python root file extension fallback

package/src/wizard-oracle.mjs

@@ -1,8 +1,28 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { join } from "node:path";
+import { spawnSync } from "node:child_process";
 import { detectStack, parseYaml } from "./config.mjs";
 import { runCmd } from "./git.mjs";
 
+/**
+ * Check if a command-line binary is available on the system PATH.
+ * @param {string} binName
+ * @returns {boolean}
+ */
+export function hasBinary(binName) {
+  if (!binName || typeof binName !== "string") return false;
+  const bin = binName.trim().split(/\s+/)[0];
+  if (!bin) return false;
+  try {
+    const isWin = process.platform === "win32";
+    const checker = isWin ? "where" : "which";
+    const res = spawnSync(checker, [bin], { stdio: "ignore" });
+    return res.status === 0;
+  } catch (_) {
+    return false;
+  }
+}
+
 /**
  * Inspect repository topology, workspace structure, and manifests to infer candidate verification oracles.
  * @param {string} [root=process.cwd()]
@@ -37,18 +57,24 @@ export function detectStackOracles(root = process.cwd()) {
 
   const packages = [];
 
-  // Check Node.json package.json scripts
+  // Check Node.js package.json scripts
   const pkgPath = join(root, "package.json");
   if (existsSync(pkgPath)) {
     try {
       const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
       const scripts = pkg.scripts || {};
+      const hasPnpm = existsSync(join(root, "pnpm-lock.yaml")) || existsSync(join(root, "pnpm-workspace.yaml"));
+      const hasYarn = existsSync(join(root, "yarn.lock"));
+      const hasBun = existsSync(join(root, "bun.lock")) || existsSync(join(root, "bun.lockb")) || existsSync(join(root, "bunfig.toml"));
+      const pm = hasPnpm ? "pnpm" : hasYarn ? "yarn" : hasBun ? "bun" : "npm";
 
-      if (scripts.test) candidates.testCmd = candidates.testCmd || "npm test";
-      if (scripts.build) candidates.buildCmd = candidates.buildCmd || "npm run build";
-      if (scripts.lint) candidates.lintCmd = "npm run lint";
+      if (scripts.test) candidates.testCmd = candidates.testCmd || (pm === "yarn" ? "yarn test" : `${pm} test`);
+      if (scripts.build) candidates.buildCmd = candidates.buildCmd || (pm === "yarn" ? "yarn build" : `${pm} run build`);
+      if (scripts.lint) candidates.lintCmd = pm === "yarn" ? "yarn lint" : `${pm} run lint`;
       if (scripts.typecheck || scripts["type-check"]) {
-        candidates.typecheckCmd = scripts.typecheck ? "npm run typecheck" : "npm run type-check";
+        candidates.typecheckCmd = scripts.typecheck
+          ? (pm === "yarn" ? "yarn typecheck" : `${pm} run typecheck`)
+          : (pm === "yarn" ? "yarn type-check" : `${pm} run type-check`);
       } else if (existsSync(join(root, "tsconfig.json"))) {
         candidates.typecheckCmd = "npx tsc --noEmit";
       }
@@ -69,7 +95,9 @@ export function detectStackOracles(root = process.cwd()) {
   if (stack.includes("go") || existsSync(join(root, "go.mod"))) {
     candidates.testCmd = candidates.testCmd || "go test ./...";
     candidates.buildCmd = candidates.buildCmd || "go build ./...";
-    candidates.lintCmd = candidates.lintCmd || "golangci-lint run";
+    if (hasBinary("golangci-lint")) {
+      candidates.lintCmd = candidates.lintCmd || "golangci-lint run";
+    }
     candidates.typecheckCmd = candidates.typecheckCmd || "go vet ./...";
   }
 
@@ -77,8 +105,14 @@ export function detectStackOracles(root = process.cwd()) {
   if (stack.includes("pytest") || existsSync(join(root, "pyproject.toml")) || existsSync(join(root, "requirements.txt"))) {
     candidates.testCmd = candidates.testCmd || "pytest";
     candidates.buildCmd = candidates.buildCmd || "";
-    candidates.lintCmd = candidates.lintCmd || "flake8 .";
-    candidates.typecheckCmd = candidates.typecheckCmd || "mypy .";
+    if (hasBinary("flake8")) {
+      candidates.lintCmd = candidates.lintCmd || "flake8 .";
+    } else if (hasBinary("ruff")) {
+      candidates.lintCmd = candidates.lintCmd || "ruff check .";
+    }
+    if (hasBinary("mypy")) {
+      candidates.typecheckCmd = candidates.typecheckCmd || "mypy .";
+    }
   }
 
   // Discover subpackages if monorepo

package/src/wizard-task.mjs

@@ -280,14 +280,15 @@ export async function runTaskCreateWizard(root = process.cwd(), options = {}) {
       if (useTodo) {
         const selectedTodo = await select(
           todos.slice(0, 10).map((t) => ({
-            label: `[${t.type}] ${t.text} (${t.file}:${t.line})`,
+            label: `[${t.type || t.tag || "TODO"}] ${t.text} (${t.file}:${t.line})`,
             value: t,
           })),
           "Select TODO Candidate",
           options
         );
-        title = `Fix ${selectedTodo.type}: ${selectedTodo.text.slice(0, 40)}`;
-        promptText = `Resolve ${selectedTodo.type} in ${selectedTodo.file} at line ${selectedTodo.line}: ${selectedTodo.text}`;
+        const todoKind = selectedTodo.type || selectedTodo.tag || "TODO";
+        title = `Fix ${todoKind}: ${selectedTodo.text.slice(0, 40)}`;
+        promptText = `Resolve ${todoKind} in ${selectedTodo.file} at line ${selectedTodo.line}: ${selectedTodo.text}`;
       }
     }