@mizyoel/mercury-mesh 0.9.4

package/.mesh/templates/multi-agent-format.md

@@ -0,0 +1,28 @@
+# Multi-Agent Artifact Format
+
+When multiple agents contribute to a final artifact (document, analysis, design), use this format. The assembled result must include:
+
+- Termination condition
+- Constraint budgets (if active)
+- Reviewer verdicts (if any)
+- Raw agent outputs appendix
+
+## Assembly Structure
+
+The assembled result goes at the top. Below it, include:
+
+```
+## APPENDIX: RAW AGENT OUTPUTS
+
+### {Name} ({Role}) — Raw Output
+{Paste agent's verbatim response here, unedited}
+
+### {Name} ({Role}) — Raw Output
+{Paste agent's verbatim response here, unedited}
+```
+
+## Appendix Rules
+
+This appendix is for diagnostic integrity. Do not edit, summarize, or polish the raw outputs. The Coordinator may not rewrite raw agent outputs; it may only paste them verbatim and assemble the final artifact above.
+
+See `.mesh/templates/run-output.md` for the complete output format template.

package/.mesh/templates/orchestration-log.md

@@ -0,0 +1,27 @@
+# Orchestration Log Entry
+
+> One file per agent spawn. Saved to `.mesh/orchestration-log/{timestamp}-{agent-name}.md`
+
+---
+
+### {timestamp} — {task summary}
+
+| Field | Value |
+|-------|-------|
+| **Agent routed** | {Name} ({Role}) |
+| **Why chosen** | {Routing rationale — what in the request matched this agent} |
+| **Mode** | {`background` / `sync`} |
+| **Why this mode** | {Brief reason — e.g., "No hard data dependencies" or "User needs to approve architecture"} |
+| **Files authorized to read** | {Exact file paths the agent was told to read} |
+| **File(s) agent must produce** | {Exact file paths the agent is expected to create or modify} |
+| **Outcome** | {Completed / Rejected by {Reviewer} / Escalated} |
+
+---
+
+## Rules
+
+1. **One file per agent spawn.** Named `{timestamp}-{agent-name}.md`.
+2. **Log BEFORE spawning.** The entry must exist before the agent runs.
+3. **Update outcome AFTER the agent completes.** Fill in the Outcome field.
+4. **Never delete or edit past entries.** Append-only.
+5. **If a reviewer rejects work,** log the rejection as a new entry with the revision agent.

package/.mesh/templates/org-autonomy-spec.md

@@ -0,0 +1,152 @@
+# Org Autonomy Runtime Spec
+
+This spec defines the first minimal runtime for concurrent, semi-autonomous departments in Org Mode.
+
+## Design Goal
+
+Departments should work concurrently and with local initiative, while remaining inside Mercury Mesh's coordinator-led control plane.
+
+The coordinator remains the global control plane.
+Department leads act as local schedulers inside an approved authority envelope.
+Department members execute leased work packets in parallel.
+
+## Core Principle
+
+**Autonomy is delegated, not sovereign.**
+
+- The coordinator still owns spawning, synthesis, and escalation.
+- Department leads may decompose and prioritize local work.
+- Members may claim queued work only within department scope.
+- Human tiers, E-Stop, and lifecycle status always override department autonomy.
+
+## Required Runtime Files
+
+When `orgMode: true`, create:
+
+```text
+.mesh/org/
+  structure.json
+  contracts/
+    {contract-name}.md
+  {department-id}/
+    charter.md
+    backlog.md
+    state.json
+```
+
+## structure.json Schema
+
+Each department entry should include:
+
+- `id`
+- `name`
+- `lead`
+- `members`
+- `domain`
+- `routingKeywords`
+- `leadStyle`
+- `authority.canDecideLocally`
+- `authority.mustEscalate`
+- `runtime.autonomyMode`
+- `runtime.maxParallelism`
+- `runtime.claimLeaseMinutes`
+- `runtime.heartbeatMinutes`
+- `runtime.backlogPath`
+- `runtime.statePath`
+- `runtime.contracts`
+
+## Work Item Lifecycle
+
+Every backlog item moves through these states:
+
+1. `queued`
+2. `claimed`
+3. `in_progress`
+4. `blocked`
+5. `review`
+6. `done`
+
+Each claimed item must record:
+
+- `workItemId`
+- `claimedBy`
+- `claimedAt`
+- `leaseExpiresAt`
+- `status`
+- `dependsOn`
+- `outputs`
+
+## Claim And Lease Protocol
+
+- A member may claim only work that is in its department domain and not already claimed.
+- Claims expire after `claimLeaseMinutes`.
+- Expired claims are re-queued by Ralph or the coordinator if `requeueExpiredClaims` is true.
+- Members must heartbeat before lease expiry when long-running work is still active.
+- Shadow agents may inspect backlog items but may not claim execution work.
+
+## Department Scheduler Loop
+
+The minimal autonomous loop is:
+
+1. Coordinator routes a mission to the relevant department lead.
+2. Lead decomposes it into work packets and writes them to `backlog.md`.
+3. Coordinator spawns eligible members against independent packets.
+4. Members execute in parallel under lease.
+5. Lead reviews probationary or blocked outputs.
+6. Scribe records outcomes; Ralph requeues stale work.
+
+This preserves the coordinator's spawn ownership while allowing local department initiative.
+
+## Cross-Department Work
+
+Cross-department work is **contract-first**.
+
+- Before departments run in parallel, define an interface contract in `.mesh/org/contracts/`.
+- Contracts define producer, consumer, inputs, outputs, invariants, and version.
+- Departments may proceed concurrently against the current contract version.
+- Contract changes trigger a lead alignment round.
+
+## Local Authority
+
+Department leads may decide locally on:
+
+- internal decomposition
+- packet assignment
+- implementation conventions inside the department
+- test strategy inside the department
+
+Department leads must escalate:
+
+- architecture changes affecting another department
+- contract changes
+- compute policy exceptions
+- roster changes
+- destructive actions outside department scope
+
+## Safety Gates
+
+Autonomy is suspended when:
+
+- `halted: true`
+- `.mesh/HALT` exists
+- the user lacks required human tier
+- the acting agent is `shadow`
+- department parallelism limit is reached
+- required contract or dependency is unresolved
+
+## Minimal Rollout
+
+Phase 1 in this repo implements:
+
+- org runtime config defaults
+- a structure template with runtime fields
+- department backlog and state templates
+- contract template
+- coordinator rules for delegated department scheduling
+
+Future phases can add:
+
+- automated claim reconciliation
+- department heartbeats
+- Ralph-driven backlog pickup cycles
+- metrics and compute budgeting per department

package/.mesh/templates/org-backlog-from-triage.js

@@ -0,0 +1,199 @@
+#!/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(),
+    triageFile: 'triage-results.json',
+    output: 'org-backlog-results.json',
+    apply: false,
+  };
+
+  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 === '--triage-file') {
+      options.triageFile = argv[index + 1];
+      index += 1;
+      continue;
+    }
+    if (arg === '--output') {
+      options.output = argv[index + 1];
+      index += 1;
+      continue;
+    }
+    if (arg === '--apply') {
+      options.apply = true;
+      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/backlog-from-triage.js [--mesh-dir .mesh] --triage-file triage-results.json --output org-backlog-results.json [--apply]');
+}
+
+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 locateBacklogTable(lines) {
+  let start = -1;
+  let end = lines.length;
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index].trim();
+    if (start === -1 && line.startsWith('| ID |')) {
+      start = index;
+      continue;
+    }
+    if (start !== -1 && line !== '' && !line.startsWith('|')) {
+      end = index;
+      break;
+    }
+  }
+  return start === -1 ? null : { start, end };
+}
+
+function serializeMarkdownTable(headers, rows) {
+  return [
+    `| ${headers.join(' | ')} |`,
+    `| ${headers.map(() => '---').join(' | ')} |`,
+    ...rows.map((row) => `| ${row.join(' | ')} |`),
+  ];
+}
+
+function updateBacklogFile(backlogPath, addRows, apply) {
+  const existing = fs.readFileSync(backlogPath, 'utf8');
+  const lines = existing.split(/\r?\n/);
+  const table = parseMarkdownTable(existing);
+  const tableIndex = locateBacklogTable(lines);
+
+  if (!table || !tableIndex) {
+    throw new Error(`Backlog table not found in ${backlogPath}`);
+  }
+
+  const headers = table.headers;
+  const updatedRows = [...table.rows, ...addRows];
+  const renderedTable = serializeMarkdownTable(headers, updatedRows);
+  const nextLines = [...lines];
+  nextLines.splice(tableIndex.start, tableIndex.end - tableIndex.start, ...renderedTable);
+
+  if (apply) {
+    fs.writeFileSync(backlogPath, `${nextLines.join('\n')}\n`, 'utf8');
+  }
+}
+
+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 triagePath = path.resolve(options.triageFile);
+
+  if (!fs.existsSync(configPath)) throw new Error(`config.json not found: ${configPath}`);
+  if (!fs.existsSync(structurePath)) throw new Error(`structure.json not found: ${structurePath}`);
+  if (!fs.existsSync(triagePath)) throw new Error(`triage file not found: ${triagePath}`);
+
+  const config = readJson(configPath);
+  if (!config.orgMode) {
+    writeJson(path.resolve(options.output), { enabled: false, reason: 'orgMode disabled', created: [] });
+    return;
+  }
+
+  const structure = readJson(structurePath);
+  const triageResults = readJson(triagePath);
+  const departments = new Map((structure.departments || []).map((department) => [department.id, department]));
+  const report = { enabled: true, apply: options.apply, generatedAt: new Date().toISOString(), created: [], skipped: [], warnings: [] };
+  const rowsByBacklog = new Map();
+
+  for (const item of triageResults) {
+    if (!item.departmentId) {
+      report.skipped.push({ issueNumber: item.issueNumber, reason: 'No department assigned' });
+      continue;
+    }
+
+    const department = departments.get(item.departmentId);
+    if (!department) {
+      report.warnings.push(`Unknown department: ${item.departmentId} for issue #${item.issueNumber}`);
+      continue;
+    }
+
+    const runtime = department.runtime || {};
+    const backlogPath = path.resolve(repoRoot, runtime.backlogPath || `${runtimeName}/org/${department.id}/backlog.md`);
+    if (!fs.existsSync(backlogPath)) {
+      report.warnings.push(`Backlog missing for department ${department.id}: ${path.relative(repoRoot, backlogPath)}`);
+      continue;
+    }
+
+    const packetId = `${department.id}-issue-${item.issueNumber}`;
+    const existing = fs.readFileSync(backlogPath, 'utf8');
+    if (existing.includes(`| ${packetId} |`)) {
+      report.skipped.push({ issueNumber: item.issueNumber, reason: `Packet already exists in ${path.relative(repoRoot, backlogPath)}` });
+      continue;
+    }
+
+    const title = (item.issueTitle || `Issue #${item.issueNumber}`).replace(/\|/g, '/');
+    const assignedTo = item.assignTo || 'unassigned';
+    const notes = [`Issue #${item.issueNumber}`, `Routed to ${assignedTo}`, item.source ? `source:${item.source}` : null].filter(Boolean).join('; ');
+    const row = [packetId, `[Issue #${item.issueNumber}] ${title}`, 'queued', 'unassigned', '-', '-', '-', notes];
+
+    if (!rowsByBacklog.has(backlogPath)) rowsByBacklog.set(backlogPath, []);
+    rowsByBacklog.get(backlogPath).push(row);
+    report.created.push({ issueNumber: item.issueNumber, backlogPath: path.relative(repoRoot, backlogPath), packetId, departmentId: item.departmentId });
+  }
+
+  for (const [backlogPath, rows] of rowsByBacklog.entries()) {
+    updateBacklogFile(backlogPath, rows, options.apply);
+  }
+
+  writeJson(path.resolve(options.output), report);
+}
+
+main();