mixdog 0.7.1

package/rules/lead/03-team.md

@@ -0,0 +1,27 @@
+# Team
+
+## Terms
+
+- **Lead**: main Claude Code session.
+- **bridge tool**: MCP dispatcher for one scoped task.
+- **role**: name from `user-workflow.json` or `hidden-roles.json`.
+- **bridge worker**: public role invoked through `bridge`.
+- **hidden role**: internal role (`explorer`, `cycle1-agent`, etc.).
+- **session/job**: runtime state; mention to users only for diagnostics.
+
+## Lead
+
+- Coordinates collaboration, approvals, bridge workers, verification,
+  Ship/git.
+- Handles small, Lead-owned, and critical config work directly.
+- Uses `# User Workflow` for role mapping; never hard-code public role
+  names.
+- Delegates implementation/state-changing work via `bridge`; retrieval
+  via Tool Routing (`recall`/`search`/`explore`). Lead keeps
+  config/git/small direct work.
+
+## Bridge Workers
+
+- `bridge.role` must match active `# User Workflow` / `# Roles`.
+- Workers cannot use `Agent`, `TaskCreate`, `TeamCreate`, or `bridge`.
+- Exception: `claude-code-guide` via `Agent` for Claude Code docs only.

package/rules/lead/04-workflow.md

@@ -0,0 +1,20 @@
+# Workflow
+
+Plan -> Execute -> Verify -> Ship -> Retro.
+
+- Plan: discuss/refine. Retrieval (`recall`/`search`/`explore`) may
+  clarify; check `recall` before re-deriving or re-proposing a decision
+  the user may already have made. Wait for explicit Execute approval.
+- Execute: use bridge workers per `# User Workflow`, or handle
+  Lead-owned work.
+- Verify: confirm via mapped role; Lead cross-checks high-risk results.
+- Ship: share results and wait. For deploy/git: status -> propose
+  commit msg -> commit on approval -> push on approval.
+- Retro: suggest reusable Skill-rule fixes surfaced by the work. Never
+  auto-edit Skills. Core memory: see `# General`. Skip when
+  nothing reusable appeared.
+
+Plan -> Execute needs explicit approval. Execute -> Verify and Ship ->
+Retro may auto-flow. Approved phases do not need repeated approval for
+ordinary actions. Still require explicit approval for code edits and
+state-changing shell execution. High-risk/deploy/push: see `# General`.

package/rules/shared/00-language.md

@@ -0,0 +1,14 @@
+# Language
+
+Plugin defaults stay language-neutral for marketplace installs.
+
+- Lead user-facing replies use the user's configured/explicit language.
+- Tool I/O, bridge briefs/responses, hidden roles, tasks, logs, stderr,
+  and retrieval queries ALWAYS use English, regardless of the input
+  brief's language. A Korean/CJK brief is an input artifact, not a
+  signal to switch response language — translate it and respond in
+  English. Identifiers, paths, and source content stay verbatim.
+- Prompts, rules, regexes, errors, and examples must not assume one
+  human language; use Unicode or locale-pluggable logic.
+- Preserve original language for user memory, chat logs, same-language
+  recall, and source data.

package/rules/shared/01-tool.md

@@ -0,0 +1,138 @@
+# Tool Routing
+
+Native tools and shell are NEVER used for IO — search, inspect, read, mutate
+files, or web access. Use the Mixdog equivalent. `bash` is the single shell
+entry point (PowerShell on Windows); native `Bash`/`PowerShell` are not used.
+
+| Native (forbidden for IO) | → Mixdog |
+|---|---|
+| `Read` | `read` |
+| `Grep` | `grep` |
+| `Glob` | `glob` |
+| `LS` / dir listing | `list` |
+| `Edit` / `NotebookEdit` | `apply_patch` (default editor) or `edit` (small exact substitution) |
+| `Write` | `write` (or `apply_patch`) |
+| Delete / remove a file | `apply_patch` (`*** Delete File: <path>`) — no native `rm`/unlink |
+| `WebSearch` | `search` |
+| `WebFetch` | `web_fetch` |
+| `Bash`/`PowerShell` (file IO) | ✗ — use the rows above; never `bash mkdir` to prep a path (`write`/`apply_patch` auto-create parent dirs), nor `touch`/`cat` (use `write`/`read`) |
+| `Bash`/`PowerShell` (git/build/test/run) | `bash` |
+| native `Agent` sub-agent to search / inspect / fetch | ✗ — call Mixdog tools directly; real sub-work goes through `bridge` |
+
+No native equivalent (use as-is): `code_graph`
+(`find_symbol`/`search`/`references`/`callers`/`imports`/`dependents`),
+`ToolSearch`. Lead progress tracking via `TaskCreate`/`TaskUpdate`/
+`TaskList` is allowed.
+
+## Decision order — pick the FIRST that matches the task
+
+1. **External / web / current docs** → `search` → `web_fetch` for bodies.
+2. **Past memory / prior decisions / session history** → `recall`.
+   Reach for it BEFORE re-deriving or re-asking — the trigger list (user
+   references earlier work, resuming a paused task, proposing a decision
+   that may already exist) is on the tool description. The SessionStart
+   inject is a thin excerpt, not the store — anything not visible there is
+   one read-only, cheap recall away.
+3. **Read the code, scope unknown / open-ended / tree-wide** → `explore`.
+   The entry point for "read the code and tell me X" and any sweep that would
+   otherwise be a long `grep`/`code_graph` storm — ONE call offloads it to a
+   sub-agent and keeps your context clean. Never a `worker`/`bridge` for
+   read-only exploration; never grep-loop it yourself.
+   explore LOCATES and DESCRIBES code — NOT an audit/review tool: its
+   bug/quality/risk claims are unverified leads; verify them (reviewer role
+   or direct reads) before acting on or reporting them. Shape every query as
+   a LOCATION/INVENTORY question ("where/which/what implements X"), never a
+   verdict question ("is X correct/missing", "are there gaps/bugs") —
+   judgment stays with the Lead or a reviewer, applied to the coordinates
+   explore returns.
+4. **Known symbol / identifier** → `code_graph` (`find_symbol` when exact;
+   `mode:search` with a keyword when you don't know the exact name — file-less,
+   lists matching symbols + locations, use INSTEAD of grepping for a symbol).
+5. **Find files by name / type / size / date** → `glob` (glob pattern, exact)
+   or `list mode:find` (name-substring / type / size / date filter).
+6. **Free-text / non-symbol content** (string literals, log lines, config keys,
+   comments) → `grep`.
+7. **Read a specific known region** → `read` (`offset`/`limit` or
+   `line`/`context`; `symbol=NAME` for a whole definition; `max_lines`/`budget`/
+   `mode` for a whole-file glance).
+8. **Edit** → `apply_patch` (default editor; large/structural, multi-hunk, or
+   multi-file) · `edit` (small exact substitution in a known spot; batch several) ·
+   `write` (new file or a full rewrite of one already read — never `write` over an
+   unread file). Batch dependent edits into ONE multi-hunk apply_patch; by default
+   keep each hunk's context minimal — the target line(s) plus only enough for a
+   unique match — so nothing surrounding is left to go stale.
+   `write`/`apply_patch` auto-create missing parent directories — never
+   `bash mkdir` to prepare an output path.
+   To delete a file, use `apply_patch` with `*** Delete File: <path>` — there is
+   no `rm` tool and `bash rm` is forbidden.
+9. **Shell** (git/build/test/run only) → `bash`.
+
+Retrieval (1–3) picks the SOURCE family first; never default to a `bridge`
+worker for a read-only lookup. Retrieval is ONE-SHOT (never reused) but fans
+out: `recall`/`search` take a query array (built-in parallelism); `explore`
+spawns one per independent area in a single batch. All read-only, so concurrent
+is safe (no worktree conflict). How to shape `explore.query` — one-line
+per-topic sub-questions, never one broad brief, no anchors/context dump — is the
+SSOT in the `explore` tool's `query` parameter description; follow it.
+
+## Broad to narrow — once scope is known
+
+`explore` (unknown scope) → `code_graph` (known identifier) → `glob`/`list` →
+`grep` (free-text / non-symbol only) → `read`. Anchor to the named file/symbol.
+A bounded / known-anchor lookup skips straight to `code_graph`/`grep` — but
+"the brief names a repo path" is NOT an anchor; anchor = a named file or symbol
+to start from. A tree-wide enumeration with no such anchor is step 3, not grep.
+
+Read what you need in ONE turn — batch a file's windows/`symbol=`s in the same
+turn, don't re-open it across later turns.
+
+## Shortest route — collapse a multi-hop search into ONE call
+
+When the shape is known, do not chain `grep` → `read`:
+- keyword / partial-or-unknown symbol name → `code_graph mode:search` (one call,
+  file-less) instead of grepping for it.
+  Seed it with a SINGLE token, not a prose phrase — multi-word phrases miss and
+  waste a call.
+- a named symbol → `code_graph find_symbol` with `body:true` (location + body +
+  callees in one call).
+- several symbols' bodies / a call chain → ONE `code_graph find_symbol
+  symbols:[...]` instead of N reads.
+- all call sites of a symbol → `callers`/`references` UNSCOPED (omit `file:`; add
+  `file:` only to narrow a too-large result).
+- an upstream/downstream call chain across several symbols → ONE
+  `callers`/`references` `symbols:[...]` (batches per chain LEVEL, not per symbol).
+- a whole function/definition → `read symbol=NAME`.
+- the lines around a hit → `grep -C`.
+- several free-text patterns at once → ONE `grep` with an array `pattern:[...]`
+  (OR-matched ripgrep regexes, ≤20; ≤5 with `multiline`) instead of repeated
+  single-pattern greps (`glob` takes an array too; for named/partial symbols use
+  `code_graph`, not `grep`).
+
+Reach for the one-shot form before adding a follow-up `read`.
+
+## Modifiers — rules that ride on top of the ladder
+
+- **Exploration budget.** Stop as soon as you can answer the task correctly —
+  don't keep searching to confirm a found answer, gather extra examples, or
+  polish phrasing. Match depth to the brief's stated thoroughness, not a default
+  of exhaustive.
+- **Concurrency.** Any calls that don't depend on each other's output go in ONE
+  message = one round-trip — read-only probes (`read`/`grep`/`glob`/`code_graph`)
+  and non-overlapping `apply_patch` edits alike. Only a true dependency chain
+  (grep → read the hit) stays serial; never run independent calls one-at-a-time.
+- **Lead-only async.** `explore` defaults to `background:true` (handle returns
+  now; the merged answer arrives via `dispatch_result`) — LEAD ONLY. Bridge
+  workers run `explore` sync (no channel for the async push) but still use it
+  over a grep storm. `explore` fans out to read-only hidden `explorer` sub-agents
+  (full worker tool schema + worker BP2 for cache parity); `recall`/`search` are
+  plain MCP tools.
+- **No waiting calls.** Never issue shell calls whose only purpose is waiting,
+  spacing, or liveness probing; report delayed/cancelled output instead.
+- **Failure circuit-breaker.** The same call failing TWICE with the same error
+  ends variant-retrying: stop, diagnose the root cause (read the error's
+  expected-vs-actual detail, inspect the target), then switch tool or
+  strategy. Blind third attempts with tweaked arguments are wasted calls —
+  the success path is one-shot; keep the failure path bounded too.
+- **No self-verification of output.** When the deliverable is code/text returned
+  in your answer, emit it directly; never `write` a scratch file or `bash` it to
+  compile/run/test your own output.

package/scripts/bootstrap.mjs

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+/**
+ * bootstrap.mjs — node-only bun bootstrap for mixdog.
+ *
+ * Ensures bun is available (system PATH or plugin-local node_modules/.bin/bun),
+ * installs it via npm if missing, then exec-proxies into scripts/run-mcp.mjs.
+ *
+ * Deps: node built-ins only (node:child_process, node:fs, node:path, node:url, node:os).
+ */
+import { spawnSync, spawn } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { prepShim } from './prep-shim.mjs';
+import { prepPatch } from './prep-patch.mjs';
+
+const scriptDir  = dirname(fileURLToPath(import.meta.url));
+const pluginRoot = dirname(scriptDir);
+const isWin      = process.platform === 'win32';
+
+// ---------------------------------------------------------------------------
+// Locate bun — returns absolute path or null.
+// ---------------------------------------------------------------------------
+function findSystemBun() {
+  const cmd = isWin ? 'where.exe' : 'which';
+  const r = spawnSync(cmd, ['bun'], { encoding: 'utf8', windowsHide: true });
+  if (r.status !== 0 || !r.stdout) return null;
+  const lines = r.stdout.split(/\r?\n/).map(l => l.trim()).filter(Boolean);
+  // On Windows `where bun` can list a .cmd/.ps1 shim before the real .exe;
+  // the downstream spawn is no-shell, so prefer an actual .exe when present.
+  const pick = isWin ? (lines.find(l => l.toLowerCase().endsWith('.exe')) ?? lines[0]) : lines[0];
+  if (!pick) return null;
+  return existsSync(pick) ? pick : null;
+}
+
+function findLocalBun() {
+  // After `npm install bun`, the .bin entry on Windows is a .cmd/.sh shim
+  // (not bun.exe), while the real binary lands in node_modules/bun/bin/. Check
+  // the package's own bin dir too — otherwise a clean-machine npm fallback can
+  // succeed yet resolveBun() still returns null and we exit "still not found".
+  const candidates = [
+    join(pluginRoot, 'node_modules', '.bin', isWin ? 'bun.exe' : 'bun'),
+    join(pluginRoot, 'node_modules', 'bun', 'bin', isWin ? 'bun.exe' : 'bun'),
+  ];
+  for (const p of candidates) if (existsSync(p)) return p;
+  return null;
+}
+
+function resolveBun() {
+  return findSystemBun() ?? findLocalBun();
+}
+
+// ---------------------------------------------------------------------------
+// npm-install bun locally if nothing found.
+// ---------------------------------------------------------------------------
+function installBunViaNpm() {
+  process.stderr.write(
+    '[bootstrap] bun not found on PATH — installing via npm (npm install --no-save --silent bun)...\n'
+  );
+  const r = spawnSync('npm', ['install', '--no-save', '--silent', 'bun'], {
+    cwd: pluginRoot,
+    stdio: 'inherit',
+    shell: false,
+    windowsHide: true,
+  });
+  if (r.status !== 0 || r.error) {
+    const hint = r.error ? ` (${r.error.message})` : '';
+    process.stderr.write(
+      `[bootstrap] npm install failed${hint}.\n` +
+      '[bootstrap] Please install bun manually: https://bun.sh\n'
+    );
+    process.exit(1);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+let bunPath = resolveBun();
+
+if (!bunPath) {
+  installBunViaNpm();
+  bunPath = resolveBun();
+  if (!bunPath) {
+    process.stderr.write(
+      '[bootstrap] bun still not found after npm install.\n' +
+      '[bootstrap] Please install bun manually: https://bun.sh\n'
+    );
+    process.exit(1);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Stage the prebuilt shim into target/release and normalize hooks.json for
+// the current OS. Best-effort: failure leaves shim absent and hooks fail-open.
+// ---------------------------------------------------------------------------
+try { prepShim(pluginRoot); } catch (err) {
+  process.stderr.write(`[bootstrap] prep-shim skipped: ${err?.message || err}\n`);
+}
+// Fire-and-forget: warms the patch binary cache so the first apply_patch
+// dispatch hits a ready file instead of paying the 2-10s download latency
+// (sync fast-path in patch.mjs would otherwise throw before the dispatch
+// async path's fetch runs).
+try { prepPatch(pluginRoot); } catch (err) {
+  process.stderr.write(`[bootstrap] prep-patch skipped: ${err?.message || err}\n`);
+}
+
+function positivePid(value) {
+  const pid = Number(value);
+  return Number.isFinite(pid) && pid > 0 ? pid : null;
+}
+
+function detectOwnerHostPid() {
+  if (isWin) {
+    try {
+      const ps = [
+        '$procs = Get-CimInstance Win32_Process | Select-Object ProcessId,ParentProcessId,Name;',
+        '$map = @{};',
+        'foreach ($p in $procs) { $map[[int]$p.ProcessId] = $p }',
+        `$cur = ${Number(process.pid)};`,
+        'for ($i = 0; $i -lt 16; $i++) {',
+        '  $p = $map[$cur]; if ($null -eq $p) { break }',
+        "  if ($p.Name -ieq 'claude.exe' -or $p.Name -ieq 'claude') { [Console]::Write($p.ProcessId); exit 0 }",
+        '  $cur = [int]$p.ParentProcessId',
+        '}',
+      ].join(' ');
+      const r = spawnSync('powershell.exe', ['-NoProfile', '-Command', ps], {
+        encoding: 'utf8',
+        timeout: 1500,
+        windowsHide: true,
+      });
+      const pid = positivePid(String(r.stdout || '').trim());
+      if (pid) return String(pid);
+    } catch {}
+  }
+  return String(positivePid(process.ppid) || positivePid(process.env.MIXDOG_OWNER_HOST_PID) || '');
+}
+
+const ownerHostPid = detectOwnerHostPid();
+
+// ---------------------------------------------------------------------------
+// Proxy into run-mcp.mjs via the resolved bun binary.
+// ---------------------------------------------------------------------------
+const child = spawn(bunPath, [join(pluginRoot, 'scripts', 'run-mcp.mjs')], {
+  stdio: 'inherit',
+  windowsHide: true,
+  env: {
+    ...process.env,
+    BUN_EXEC_PATH: bunPath,
+    MIXDOG_OWNER_HOST_PID: ownerHostPid,
+  },
+});
+
+child.on('error', (err) => {
+  process.stderr.write(`[bootstrap] failed to start run-mcp.mjs: ${err.message}\n`);
+  process.exit(1);
+});
+
+child.on('exit', (code) => {
+  process.exit(code ?? 0);
+});
+
+function forward(sig) {
+  try { child.kill(sig); } catch { /* child already gone */ }
+}
+process.on('SIGTERM', () => forward('SIGTERM'));
+process.on('SIGINT',  () => forward('SIGINT'));
+
+// stdin EOF / close = Claude Code (parent) disconnected its end of stdio.
+// run-mcp.mjs handles this in its own layer, but if a race leaves the bun
+// child unable to fire `exit` (sudden stdio break, abnormal bun termination),
+// bootstrap.mjs would otherwise wait forever, accumulating wrapper-layer
+// zombies across reconnects. Force teardown: SIGTERM child, give it 2s,
+// then SIGKILL + self-exit. Mirrors run-mcp.mjs stdin EOF invariant
+// (commit 754ab7d) at the bootstrap layer.
+process.stdin.on('close', () => {
+  try { child.kill('SIGTERM'); } catch {}
+  setTimeout(() => {
+    try { child.kill('SIGKILL'); } catch {}
+    process.exit(0);
+  }, 2000).unref();
+});
+process.stdin.on('error', () => process.exit(0));