@mizyoel/mercury-mesh 0.9.4

package/.mesh/templates/org-status.js

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const RUNTIME_DIR_CANDIDATES = ['.mesh', '.mercury'];
+
+function defaultRuntimeDir() {
+  return RUNTIME_DIR_CANDIDATES.find((candidate) => fs.existsSync(candidate)) || '.mesh';
+}
+
+function runtimeDirName(runtimeDir) {
+  return path.basename(path.resolve(runtimeDir));
+}
+
+function parseArgs(argv) {
+  const options = {
+    meshDir: defaultRuntimeDir(),
+    output: 'org-status.json',
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--mesh-dir') {
+      options.meshDir = argv[index + 1];
+      index += 1;
+      continue;
+    }
+    if (arg === '--output') {
+      options.output = argv[index + 1];
+      index += 1;
+      continue;
+    }
+    if (arg === '--help' || arg === '-h') {
+      printUsage();
+      process.exit(0);
+    }
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+
+  return options;
+}
+
+function printUsage() {
+  console.log('Usage: node <runtime>/org/status.js [--mesh-dir .mesh] --output org-status.json');
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function writeJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+function parseMarkdownTable(content) {
+  const lines = content.split(/\r?\n/);
+  const rows = [];
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('|') || !trimmed.endsWith('|')) continue;
+    const cells = trimmed.slice(1, -1).split('|').map((cell) => cell.trim());
+    if (cells.every((cell) => /^-+$/.test(cell))) continue;
+    rows.push(cells);
+  }
+
+  if (rows.length < 2) return null;
+  return { headers: rows[0], rows: rows.slice(1) };
+}
+
+function summarizeBacklog(backlogPath) {
+  if (!fs.existsSync(backlogPath)) {
+    return { exists: false, counts: {}, blocked: [] };
+  }
+
+  const table = parseMarkdownTable(fs.readFileSync(backlogPath, 'utf8'));
+  if (!table) {
+    return { exists: true, counts: {}, blocked: [], warning: 'Backlog table not found' };
+  }
+
+  const headerIndex = new Map(table.headers.map((header, index) => [header.toLowerCase(), index]));
+  const idIndex = headerIndex.get('id');
+  const statusIndex = headerIndex.get('status');
+  const notesIndex = headerIndex.get('notes');
+  const counts = {};
+  const blocked = [];
+
+  for (const row of table.rows) {
+    const status = statusIndex >= 0 ? row[statusIndex] : 'unknown';
+    counts[status] = (counts[status] || 0) + 1;
+    if (status === 'blocked') {
+      blocked.push({
+        id: idIndex >= 0 ? row[idIndex] : 'unknown',
+        notes: notesIndex >= 0 ? row[notesIndex] : '',
+      });
+    }
+  }
+
+  return { exists: true, counts, blocked };
+}
+
+function summarizeState(statePath, heartbeatMinutes) {
+  if (!fs.existsSync(statePath)) {
+    return { exists: false, activeClaims: 0, staleHeartbeat: false, parallelismBreach: false };
+  }
+
+  const state = readJson(statePath);
+  const activeClaims = Array.isArray(state.activeClaims) ? state.activeClaims : [];
+  const heartbeat = state.lastHeartbeatAt ? new Date(state.lastHeartbeatAt) : null;
+  const staleHeartbeat = !heartbeat || Number.isNaN(heartbeat.valueOf())
+    ? true
+    : (Date.now() - heartbeat.valueOf()) > heartbeatMinutes * 60 * 1000;
+
+  return {
+    exists: true,
+    activeClaims: activeClaims.length,
+    staleHeartbeat,
+    lastHeartbeatAt: state.lastHeartbeatAt || null,
+    blockedCount: Array.isArray(state.blocked) ? state.blocked.length : 0,
+  };
+}
+
+function main() {
+  const options = parseArgs(process.argv.slice(2));
+  const meshDir = path.resolve(options.meshDir);
+  const runtimeName = runtimeDirName(meshDir);
+  const repoRoot = path.dirname(meshDir);
+  const configPath = path.join(meshDir, 'config.json');
+  const structurePath = path.join(meshDir, 'org', 'structure.json');
+  const contractsDir = path.join(meshDir, 'org', 'contracts');
+
+  if (!fs.existsSync(configPath)) {
+    throw new Error(`config.json not found: ${configPath}`);
+  }
+
+  const config = readJson(configPath);
+  if (!config.orgMode || !fs.existsSync(structurePath)) {
+    writeJson(path.resolve(options.output), {
+      enabled: false,
+      reason: `orgMode disabled or ${runtimeName}/org/structure.json missing`,
+      departments: [],
+      contracts: [],
+    });
+    return;
+  }
+
+  const structure = readJson(structurePath);
+  const departments = Array.isArray(structure.departments) ? structure.departments : [];
+  const heartbeatMinutes = (config.orgConfig && config.orgConfig.heartbeatMinutes) || 15;
+  const maxParallelismDefault = (config.orgConfig && config.orgConfig.maxParallelismPerDepartment) || 3;
+
+  const departmentReports = departments.map((department) => {
+    const runtime = department.runtime || {};
+    const backlogPath = path.resolve(repoRoot, runtime.backlogPath || `${runtimeName}/org/${department.id}/backlog.md`);
+    const statePath = path.resolve(repoRoot, runtime.statePath || `${runtimeName}/org/${department.id}/state.json`);
+    const backlog = summarizeBacklog(backlogPath);
+    const state = summarizeState(statePath, runtime.heartbeatMinutes || heartbeatMinutes);
+    const maxParallelism = runtime.maxParallelism || maxParallelismDefault;
+
+    return {
+      id: department.id,
+      name: department.name,
+      lead: department.lead,
+      backlogPath: path.relative(repoRoot, backlogPath),
+      statePath: path.relative(repoRoot, statePath),
+      contracts: runtime.contracts || [],
+      backlog,
+      state: {
+        ...state,
+        maxParallelism,
+        parallelismBreach: state.activeClaims > maxParallelism,
+      },
+    };
+  });
+
+  const contracts = fs.existsSync(contractsDir)
+    ? fs.readdirSync(contractsDir)
+        .filter((fileName) => fileName.endsWith('.md'))
+        .map((fileName) => path.posix.join(runtimeName, 'org', 'contracts', fileName))
+    : [];
+
+  writeJson(path.resolve(options.output), {
+    enabled: true,
+    generatedAt: new Date().toISOString(),
+    departments: departmentReports,
+    contracts,
+  });
+}
+
+main();

package/.mesh/templates/org-structure.json

@@ -0,0 +1,38 @@
+{
+  "departments": [
+    {
+      "id": "frontend",
+      "name": "Frontend",
+      "lead": "{CastName}",
+      "members": ["{CastName}"],
+      "domain": ["ui", "components", "pages", "design-system"],
+      "routingKeywords": ["ui", "component", "page", "css", "react"],
+      "leadStyle": "player-coach",
+      "authority": {
+        "canDecideLocally": [
+          "component boundaries",
+          "local naming",
+          "test strategy inside department"
+        ],
+        "mustEscalate": [
+          "cross-department API changes",
+          "shared architecture changes",
+          "roster changes"
+        ]
+      },
+      "runtime": {
+        "autonomyMode": "delegated",
+        "maxParallelism": 3,
+        "claimLeaseMinutes": 30,
+        "heartbeatMinutes": 15,
+        "backlogPath": ".mesh/org/frontend/backlog.md",
+        "statePath": ".mesh/org/frontend/state.json",
+        "contracts": [".mesh/org/contracts/ui-api.md"]
+      }
+    }
+  ],
+  "crossDepartment": {
+    "strategy": "contract-first",
+    "escalation": "lead-alignment"
+  }
+}

package/.mesh/templates/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/.mesh/templates/plugin-marketplace.md

@@ -0,0 +1,49 @@
+# Plugin Marketplace
+
+Plugins are curated agent templates, skills, instructions, and prompts shared by the community via GitHub repositories (e.g., `github/awesome-copilot`, `anthropics/skills`). They provide ready-made expertise for common domains — cloud platforms, frameworks, testing strategies, etc.
+
+## Marketplace State
+
+Registered marketplace sources are stored in `.mesh/plugins/marketplaces.json`:
+
+```json
+{
+  "marketplaces": [
+    {
+      "name": "awesome-copilot",
+      "source": "github/awesome-copilot",
+      "added_at": "2026-02-14T00:00:00Z"
+    }
+  ]
+}
+```
+
+## CLI Commands
+
+Users manage marketplaces via the CLI:
+- `Mercury Mesh plugin marketplace add {owner/repo}` — Register a GitHub repo as a marketplace source
+- `Mercury Mesh plugin marketplace remove {name}` — Remove a registered marketplace
+- `Mercury Mesh plugin marketplace list` — List registered marketplaces
+- `Mercury Mesh plugin marketplace browse {name}` — List available plugins in a marketplace
+
+## When to Browse
+
+During the **Adding Team Members** flow, AFTER allocating a name but BEFORE generating the charter:
+
+1. Read `.mesh/plugins/marketplaces.json`. If the file doesn't exist or `marketplaces` is empty, skip silently.
+2. For each registered marketplace, search for plugins whose name or description matches the new member's role or domain keywords.
+3. Present matching plugins to the user: *"Found '{plugin-name}' in {marketplace} marketplace — want me to install it as a skill for {CastName}?"*
+4. If the user accepts, install the plugin (see below). If they decline or skip, proceed without it.
+
+## How to Install a Plugin
+
+1. Read the plugin content from the marketplace repository (the plugin's `SKILL.md` or equivalent).
+2. Copy it into the agent's skills directory: `.mesh/skills/{plugin-name}/SKILL.md`
+3. If the plugin includes charter-level instructions (role boundaries, tool preferences), merge those into the agent's `charter.md`.
+4. Log the installation in the agent's `history.md`: *"📦 Plugin '{plugin-name}' installed from {marketplace}."*
+
+## Graceful Degradation
+
+- **No marketplaces configured:** Skip the marketplace check entirely. No warning, no prompt.
+- **Marketplace unreachable:** Warn the user (*"⚠ Couldn't reach {marketplace} — continuing without it"*) and proceed with team member creation normally.
+- **No matching plugins:** Inform the user (*"No matching plugins found in configured marketplaces"*) and proceed.

package/.mesh/templates/ralph-circuit-breaker.md

@@ -0,0 +1,313 @@
+# Ralph Circuit Breaker — Model Rate Limit Fallback
+
+> Classic circuit breaker pattern (Hystrix / Polly / Resilience4j) applied to Copilot model selection.
+> When the preferred model hits rate limits, Ralph automatically degrades to free-tier models, then self-heals.
+
+## Problem
+
+When running multiple Ralph instances across repos, Copilot model rate limits cause cascading failures.
+All Ralphs fail simultaneously when the preferred model (e.g., `claude-sonnet-4.6`) hits quota.
+
+Premium models burn quota fast:
+| Model | Multiplier | Risk |
+|-------|-----------|------|
+| `claude-sonnet-4.6` | 1x | Moderate with many Ralphs |
+| `claude-opus-4.6` | 10x | High |
+| `gpt-5.4` | 50x | Very high |
+| `gpt-5.4-mini` | **0x** | **Free — unlimited** |
+| `gpt-5-mini` | **0x** | **Free — unlimited** |
+| `gpt-4.1` | **0x** | **Free — unlimited** |
+
+## Circuit Breaker States
+
+```
+┌─────────┐   rate limit error    ┌────────┐
+│ CLOSED  │ ───────────────────►  │  OPEN  │
+│ (normal)│                       │(fallback)│
+└────┬────┘   ◄──────────────── └────┬────┘
+     │        2 consecutive          │
+     │        successes              │ cooldown expires
+     │                               ▼
+     │                          ┌──────────┐
+     └───── success ◄────────  │HALF-OPEN │
+             (close)            │ (testing) │
+                                └──────────┘
+```
+
+### CLOSED (normal operation)
+- Use preferred model from config
+- Every successful response confirms circuit stays closed
+- On rate limit error → transition to OPEN
+
+### OPEN (rate limited — fallback active)
+- Fall back through the free-tier model chain:
+  1. `gpt-5.4-mini`
+  2. `gpt-5-mini`
+  3. `gpt-4.1`
+- Start cooldown timer (default: 10 minutes)
+- When cooldown expires → transition to HALF-OPEN
+
+### HALF-OPEN (testing recovery)
+- Try preferred model again
+- If 2 consecutive successes → transition to CLOSED
+- If rate limit error → back to OPEN, reset cooldown
+
+## State File: `.mesh/ralph-circuit-breaker.json`
+
+```json
+{
+  "state": "closed",
+  "preferredModel": "claude-sonnet-4.6",
+  "fallbackChain": ["gpt-5.4-mini", "gpt-5-mini", "gpt-4.1"],
+  "currentFallbackIndex": 0,
+  "cooldownMinutes": 10,
+  "openedAt": null,
+  "halfOpenSuccesses": 0,
+  "consecutiveFailures": 0,
+  "metrics": {
+    "totalFallbacks": 0,
+    "totalRecoveries": 0,
+    "lastFallbackAt": null,
+    "lastRecoveryAt": null
+  }
+}
+```
+
+## PowerShell Functions
+
+Paste these into your `ralph-watch.ps1` or source them from a shared module.
+
+### `Get-CircuitBreakerState`
+
+```powershell
+function Get-CircuitBreakerState {
+    param([string]$StateFile = ".mesh/ralph-circuit-breaker.json")
+
+    if (-not (Test-Path $StateFile)) {
+        $default = @{
+            state              = "closed"
+            preferredModel     = "claude-sonnet-4.6"
+            fallbackChain      = @("gpt-5.4-mini", "gpt-5-mini", "gpt-4.1")
+            currentFallbackIndex = 0
+            cooldownMinutes    = 10
+            openedAt           = $null
+            halfOpenSuccesses  = 0
+            consecutiveFailures = 0
+            metrics            = @{
+                totalFallbacks  = 0
+                totalRecoveries = 0
+                lastFallbackAt  = $null
+                lastRecoveryAt  = $null
+            }
+        }
+        $default | ConvertTo-Json -Depth 3 | Set-Content $StateFile
+        return $default
+    }
+
+    return (Get-Content $StateFile -Raw | ConvertFrom-Json)
+}
+```
+
+### `Save-CircuitBreakerState`
+
+```powershell
+function Save-CircuitBreakerState {
+    param(
+        [object]$State,
+        [string]$StateFile = ".mesh/ralph-circuit-breaker.json"
+    )
+
+    $State | ConvertTo-Json -Depth 3 | Set-Content $StateFile
+}
+```
+
+### `Get-CurrentModel`
+
+Returns the model Ralph should use right now, based on circuit state.
+
+```powershell
+function Get-CurrentModel {
+    param([string]$StateFile = ".mesh/ralph-circuit-breaker.json")
+
+    $cb = Get-CircuitBreakerState -StateFile $StateFile
+
+    switch ($cb.state) {
+        "closed" {
+            return $cb.preferredModel
+        }
+        "open" {
+            # Check if cooldown has expired
+            if ($cb.openedAt) {
+                $opened = [DateTime]::Parse($cb.openedAt)
+                $elapsed = (Get-Date) - $opened
+                if ($elapsed.TotalMinutes -ge $cb.cooldownMinutes) {
+                    # Transition to half-open
+                    $cb.state = "half-open"
+                    $cb.halfOpenSuccesses = 0
+                    Save-CircuitBreakerState -State $cb -StateFile $StateFile
+                    Write-Host "  [circuit-breaker] Cooldown expired. Testing preferred model..." -ForegroundColor Yellow
+                    return $cb.preferredModel
+                }
+            }
+            # Still in cooldown — use fallback
+            $idx = [Math]::Min($cb.currentFallbackIndex, $cb.fallbackChain.Count - 1)
+            return $cb.fallbackChain[$idx]
+        }
+        "half-open" {
+            return $cb.preferredModel
+        }
+        default {
+            return $cb.preferredModel
+        }
+    }
+}
+```
+
+### `Update-CircuitBreakerOnSuccess`
+
+Call after every successful model response.
+
+```powershell
+function Update-CircuitBreakerOnSuccess {
+    param([string]$StateFile = ".mesh/ralph-circuit-breaker.json")
+
+    $cb = Get-CircuitBreakerState -StateFile $StateFile
+    $cb.consecutiveFailures = 0
+
+    if ($cb.state -eq "half-open") {
+        $cb.halfOpenSuccesses++
+        if ($cb.halfOpenSuccesses -ge 2) {
+            # Recovery! Close the circuit
+            $cb.state = "closed"
+            $cb.openedAt = $null
+            $cb.halfOpenSuccesses = 0
+            $cb.currentFallbackIndex = 0
+            $cb.metrics.totalRecoveries++
+            $cb.metrics.lastRecoveryAt = (Get-Date).ToString("o")
+            Save-CircuitBreakerState -State $cb -StateFile $StateFile
+            Write-Host "  [circuit-breaker] RECOVERED — back to preferred model ($($cb.preferredModel))" -ForegroundColor Green
+            return
+        }
+        Save-CircuitBreakerState -State $cb -StateFile $StateFile
+        Write-Host "  [circuit-breaker] Half-open success $($cb.halfOpenSuccesses)/2" -ForegroundColor Yellow
+        return
+    }
+
+    # closed state — nothing to do
+}
+```
+
+### `Update-CircuitBreakerOnRateLimit`
+
+Call when a model response indicates rate limiting (HTTP 429 or error message containing "rate limit").
+
+```powershell
+function Update-CircuitBreakerOnRateLimit {
+    param([string]$StateFile = ".mesh/ralph-circuit-breaker.json")
+
+    $cb = Get-CircuitBreakerState -StateFile $StateFile
+    $cb.consecutiveFailures++
+
+    if ($cb.state -eq "closed" -or $cb.state -eq "half-open") {
+        # Open the circuit
+        $cb.state = "open"
+        $cb.openedAt = (Get-Date).ToString("o")
+        $cb.halfOpenSuccesses = 0
+        $cb.currentFallbackIndex = 0
+        $cb.metrics.totalFallbacks++
+        $cb.metrics.lastFallbackAt = (Get-Date).ToString("o")
+        Save-CircuitBreakerState -State $cb -StateFile $StateFile
+
+        $fallbackModel = $cb.fallbackChain[0]
+        Write-Host "  [circuit-breaker] RATE LIMITED — falling back to $fallbackModel (cooldown: $($cb.cooldownMinutes)m)" -ForegroundColor Red
+        return
+    }
+
+    if ($cb.state -eq "open") {
+        # Already open — try next fallback in chain if current one also fails
+        if ($cb.currentFallbackIndex -lt ($cb.fallbackChain.Count - 1)) {
+            $cb.currentFallbackIndex++
+            $nextModel = $cb.fallbackChain[$cb.currentFallbackIndex]
+            Write-Host "  [circuit-breaker] Fallback also limited — trying $nextModel" -ForegroundColor Red
+        }
+        # Reset cooldown timer
+        $cb.openedAt = (Get-Date).ToString("o")
+        Save-CircuitBreakerState -State $cb -StateFile $StateFile
+    }
+}
+```
+
+## Integration with ralph-watch.ps1
+
+In your Ralph polling loop, wrap the model selection:
+
+```powershell
+# At the top of your polling loop
+$model = Get-CurrentModel
+
+# When invoking copilot CLI
+$result = copilot-cli --model $model ...
+
+# After the call
+if ($result -match "rate.?limit" -or $LASTEXITCODE -eq 429) {
+    Update-CircuitBreakerOnRateLimit
+} else {
+    Update-CircuitBreakerOnSuccess
+}
+```
+
+### Full integration example
+
+```powershell
+# Source the circuit breaker functions
+. .mesh-templates/ralph-circuit-breaker-functions.ps1
+
+while ($true) {
+    $model = Get-CurrentModel
+    Write-Host "Polling with model: $model"
+
+    try {
+        # Your existing Ralph logic here, but pass $model
+        $response = Invoke-RalphCycle -Model $model
+
+        # Success path
+        Update-CircuitBreakerOnSuccess
+    }
+    catch {
+        if ($_.Exception.Message -match "rate.?limit|429|quota|Too Many Requests") {
+            Update-CircuitBreakerOnRateLimit
+            # Retry immediately with fallback model
+            continue
+        }
+        # Other errors — handle normally
+        throw
+    }
+
+    Start-Sleep -Seconds $pollInterval
+}
+```
+
+## Configuration
+
+Override defaults by editing `.mesh/ralph-circuit-breaker.json`:
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `preferredModel` | `claude-sonnet-4.6` | Model to use when circuit is closed |
+| `fallbackChain` | `["gpt-5.4-mini", "gpt-5-mini", "gpt-4.1"]` | Ordered fallback models (all free-tier) |
+| `cooldownMinutes` | `10` | How long to wait before testing recovery |
+
+## Metrics
+
+The state file tracks operational metrics:
+
+- **totalFallbacks** — How many times the circuit opened
+- **totalRecoveries** — How many times it recovered to preferred model
+- **lastFallbackAt** — ISO timestamp of last rate limit event
+- **lastRecoveryAt** — ISO timestamp of last successful recovery
+
+Query metrics with:
+```powershell
+$cb = Get-Content .mesh/ralph-circuit-breaker.json | ConvertFrom-Json
+Write-Host "Fallbacks: $($cb.metrics.totalFallbacks) | Recoveries: $($cb.metrics.totalRecoveries)"
+```