@chllming/wave-orchestration 0.5.1

package/scripts/wave-orchestrator/ledger.mjs

@@ -0,0 +1,332 @@
+import {
+  DEFAULT_DOCUMENTATION_AGENT_ID,
+  DEFAULT_EVALUATOR_AGENT_ID,
+  DEFAULT_INTEGRATION_AGENT_ID,
+} from "./config.mjs";
+import {
+  validateDocumentationClosureSummary,
+  validateEvaluatorSummary,
+  validateImplementationSummary,
+} from "./agent-state.mjs";
+import { openClarificationLinkedRequests } from "./coordination-store.mjs";
+import { buildHelperTasks } from "./routing-state.mjs";
+import { readJsonOrNull, toIsoTimestamp, writeJsonAtomic } from "./shared.mjs";
+
+function taskId(prefix, suffix) {
+  return `${prefix}:${suffix}`;
+}
+
+function taskStateFromValidation(validation) {
+  if (validation?.ok) {
+    return "done";
+  }
+  return validation ? "blocked" : "planned";
+}
+
+function openHighPriorityBlockers(state) {
+  return (state?.blockers || []).filter(
+    (record) =>
+      ["open", "acknowledged", "in_progress"].includes(record.status) &&
+      ["high", "urgent"].includes(record.priority),
+  );
+}
+
+function openClarifications(state) {
+  return (state?.clarifications || []).filter((record) =>
+    ["open", "acknowledged", "in_progress"].includes(record.status),
+  );
+}
+
+export function buildSeedWaveLedger({
+  lane,
+  wave,
+  evaluatorAgentId = DEFAULT_EVALUATOR_AGENT_ID,
+  integrationAgentId = DEFAULT_INTEGRATION_AGENT_ID,
+  documentationAgentId = DEFAULT_DOCUMENTATION_AGENT_ID,
+}) {
+  const tasks = [];
+  for (const agent of wave.agents) {
+    const kind =
+      agent.agentId === evaluatorAgentId
+        ? "evaluator"
+        : agent.agentId === integrationAgentId
+          ? "integration"
+          : agent.agentId === documentationAgentId
+            ? "documentation"
+            : "implementation";
+    tasks.push({
+      id: taskId(kind, agent.agentId),
+      title: `${agent.agentId}: ${agent.title}`,
+      owner: agent.agentId,
+      kind,
+      dependsOn: [],
+      state: "planned",
+      proofState: "pending",
+      docState: "pending",
+      infraState: "n/a",
+      priority:
+        kind === "implementation" ? "normal" : kind === "integration" ? "high" : "high",
+      artifactRefs: agent.ownedPaths || [],
+      runtime: agent.executorResolved
+        ? {
+            executorId: agent.executorResolved.id,
+            role: agent.executorResolved.role,
+            profile: agent.executorResolved.profile,
+            selectedBy: agent.executorResolved.selectedBy,
+            fallbacks: agent.executorResolved.fallbacks || [],
+            fallbackUsed: agent.executorResolved.fallbackUsed === true,
+          }
+        : null,
+    });
+  }
+  for (const promotion of wave.componentPromotions || []) {
+    tasks.push({
+      id: taskId("component", promotion.componentId),
+      title: `Promote ${promotion.componentId} to ${promotion.targetLevel}`,
+      owner: null,
+      kind: "component",
+      dependsOn: [],
+      state: "planned",
+      proofState: "pending",
+      docState: "pending",
+      infraState: "n/a",
+      priority: "high",
+      artifactRefs: [promotion.componentId],
+      runtime: null,
+    });
+  }
+  return {
+    wave: wave.wave,
+    lane,
+    attempt: 0,
+    phase: "planned",
+    tasks,
+    blockers: [],
+    openRequests: [],
+    openClarifications: [],
+    clarificationLinkedRequests: [],
+    humanFeedback: [],
+    humanEscalations: [],
+    integrationState: "pending",
+    docClosureState: "pending",
+    evaluatorState: "pending",
+    updatedAt: toIsoTimestamp(),
+  };
+}
+
+function derivePhase({
+  tasks,
+  integrationSummary,
+  docValidation,
+  evaluatorValidation,
+  state,
+  dependencySnapshot = null,
+}) {
+  const blockers = openHighPriorityBlockers(state);
+  if (blockers.length > 0) {
+    return "blocked";
+  }
+  if (
+    openClarifications(state).length > 0 ||
+    openClarificationLinkedRequests(state).length > 0
+  ) {
+    return "clarifying";
+  }
+  const dependencyBlockers =
+    (dependencySnapshot?.requiredInbound || []).length + (dependencySnapshot?.requiredOutbound || []).length;
+  if (dependencyBlockers > 0) {
+    return "blocked";
+  }
+  const blockingHelperTasks = tasks.filter((task) =>
+    ["helper", "dependency", "dependency-outbound"].includes(task.kind) &&
+    !["done", "closed", "resolved"].includes(task.state),
+  );
+  if (blockingHelperTasks.length > 0) {
+    return blockingHelperTasks.some((task) => task.state === "blocked") ? "blocked" : "running";
+  }
+  const implementationTasks = tasks.filter((task) => task.kind === "implementation");
+  const allImplementationDone = implementationTasks.every((task) => task.state === "done");
+  if (!allImplementationDone) {
+    return "running";
+  }
+  if (integrationSummary?.recommendation !== "ready-for-doc-closure") {
+    return "integrating";
+  }
+  if (!docValidation?.ok) {
+    return "docs-closure";
+  }
+  if (!evaluatorValidation?.ok) {
+    return "evaluator-closure";
+  }
+  return "completed";
+}
+
+export function deriveWaveLedger({
+  lane,
+  wave,
+  summariesByAgentId = {},
+  coordinationState = null,
+  integrationSummary = null,
+  docsQueue = null,
+  attempt = 0,
+  evaluatorAgentId = DEFAULT_EVALUATOR_AGENT_ID,
+  integrationAgentId = DEFAULT_INTEGRATION_AGENT_ID,
+  documentationAgentId = DEFAULT_DOCUMENTATION_AGENT_ID,
+  capabilityAssignments = [],
+  dependencySnapshot = null,
+}) {
+  const seed = buildSeedWaveLedger({
+    lane,
+    wave,
+    evaluatorAgentId,
+    integrationAgentId,
+    documentationAgentId,
+  });
+  const primaryTasks = seed.tasks.map((task) => {
+    const agent = wave.agents.find((item) => item.agentId === task.owner);
+    const summary = task.owner ? summariesByAgentId[task.owner] : null;
+    if (task.kind === "implementation" && agent) {
+      const validation = validateImplementationSummary(agent, summary);
+      return {
+        ...task,
+        state: taskStateFromValidation(validation),
+        proofState: validation.ok ? "met" : "gap",
+        docState: summary?.docDelta?.state || "pending",
+      };
+    }
+    if (task.kind === "documentation" && agent) {
+      const validation = validateDocumentationClosureSummary(agent, summary);
+      return {
+        ...task,
+        state: taskStateFromValidation(validation),
+        proofState: "n/a",
+        docState: validation.ok ? "closed" : "open",
+      };
+    }
+    if (task.kind === "evaluator" && agent) {
+      const validation = validateEvaluatorSummary(agent, summary);
+      return {
+        ...task,
+        state: taskStateFromValidation(validation),
+        proofState: validation.ok ? "met" : "gap",
+        docState: "n/a",
+      };
+    }
+    if (task.kind === "integration") {
+      const ready = integrationSummary?.recommendation === "ready-for-doc-closure";
+      return {
+        ...task,
+        state: ready ? "done" : integrationSummary ? "blocked" : "planned",
+        proofState: ready ? "met" : "pending",
+        docState: "n/a",
+      };
+    }
+    if (task.kind === "component") {
+      const owners = wave.agents.filter((agent) =>
+        Array.isArray(agent.components) && agent.components.includes(task.artifactRefs[0]),
+      );
+      const complete = owners.length > 0 && owners.every((agent) => {
+        const summary = summariesByAgentId[agent.agentId];
+        return Array.isArray(summary?.components)
+          ? summary.components.some(
+              (component) =>
+                component.componentId === task.artifactRefs[0] && component.state === "met",
+            )
+          : false;
+      });
+      return {
+        ...task,
+        state: complete ? "done" : "blocked",
+        proofState: complete ? "met" : "gap",
+        docState:
+          Array.isArray(docsQueue?.items) && docsQueue.items.some((item) => item.kind === "component-matrix")
+            ? "pending"
+            : "n/a",
+      };
+    }
+    return task;
+  });
+  const helperTasks = buildHelperTasks({
+    wave,
+    assignments: capabilityAssignments,
+    dependencySnapshot,
+    docsQueue,
+    documentationAgentId,
+  });
+  const tasks = [...primaryTasks, ...helperTasks];
+  const docAgent = wave.agents.find((agent) => agent.agentId === documentationAgentId);
+  const evaluatorAgent = wave.agents.find((agent) => agent.agentId === evaluatorAgentId);
+  const docValidation = docAgent
+    ? validateDocumentationClosureSummary(docAgent, summariesByAgentId[documentationAgentId])
+    : { ok: true };
+  const evaluatorValidation = evaluatorAgent
+    ? validateEvaluatorSummary(evaluatorAgent, summariesByAgentId[evaluatorAgentId])
+    : { ok: true };
+  return {
+    wave: wave.wave,
+    lane,
+    attempt,
+    phase: derivePhase({
+      tasks,
+      integrationSummary,
+      docValidation,
+      evaluatorValidation,
+      state: coordinationState,
+      dependencySnapshot,
+    }),
+    tasks,
+    blockers: (coordinationState?.blockers || []).map((record) => record.id),
+    openClarifications: openClarifications(coordinationState).map((record) => record.id),
+    clarificationLinkedRequests: openClarificationLinkedRequests(coordinationState).map(
+      (record) => record.id,
+    ),
+    openRequests: (coordinationState?.requests || [])
+      .filter((record) => ["open", "acknowledged", "in_progress"].includes(record.status))
+      .map((record) => record.id),
+    capabilityAssignments: (capabilityAssignments || []).map((assignment) => ({
+      id: assignment.id,
+      requestId: assignment.requestId,
+      assignedAgentId: assignment.assignedAgentId,
+      target: assignment.target,
+      targetType: assignment.targetType,
+      capability: assignment.capability,
+      blocking: assignment.blocking,
+      assignmentReason: assignment.assignmentReason,
+      state: assignment.state,
+    })),
+    dependencySnapshot: dependencySnapshot
+      ? {
+          openInbound: dependencySnapshot.openInbound.map((record) => record.id),
+          openOutbound: dependencySnapshot.openOutbound.map((record) => record.id),
+          requiredInbound: dependencySnapshot.requiredInbound.map((record) => record.id),
+          requiredOutbound: dependencySnapshot.requiredOutbound.map((record) => record.id),
+          unresolvedInboundAssignments: dependencySnapshot.unresolvedInboundAssignments.map(
+            (record) => record.id,
+          ),
+        }
+      : null,
+    humanFeedback: [
+      ...(coordinationState?.humanFeedback || [])
+        .filter((record) => ["open", "acknowledged", "in_progress"].includes(record.status))
+        .map((record) => record.id),
+      ...(coordinationState?.humanEscalations || [])
+        .filter((record) => ["open", "acknowledged", "in_progress"].includes(record.status))
+        .map((record) => record.id),
+    ],
+    humanEscalations: (coordinationState?.humanEscalations || [])
+      .filter((record) => ["open", "acknowledged", "in_progress"].includes(record.status))
+      .map((record) => record.id),
+    integrationState: integrationSummary?.recommendation || "pending",
+    docClosureState: docValidation.ok ? "closed" : "open",
+    evaluatorState: evaluatorValidation.ok ? "pass" : "open",
+    updatedAt: toIsoTimestamp(),
+  };
+}
+
+export function writeWaveLedger(filePath, payload) {
+  writeJsonAtomic(filePath, payload);
+}
+
+export function readWaveLedger(filePath) {
+  return readJsonOrNull(filePath);
+}

package/scripts/wave-orchestrator/local-executor.mjs

@@ -0,0 +1,263 @@
+import fs from "node:fs";
+import path from "node:path";
+import { REPO_ROOT, ensureDirectory } from "./shared.mjs";
+
+function titleFromPath(relPath) {
+  return path
+    .basename(relPath, path.extname(relPath))
+    .replace(/[-_]+/g, " ")
+    .replace(/\b\w/g, (char) => char.toUpperCase());
+}
+
+function extractAssignedPrompt(raw) {
+  const match = raw.match(/Assigned implementation prompt:\s*```[a-zA-Z0-9_-]*\n([\s\S]*?)\n```/);
+  return match ? match[1].trim() : raw;
+}
+
+function extractAgentId(rawPrompt) {
+  const match = String(rawPrompt || "").match(
+    /You are the Wave executor running Wave \d+ \/ Agent ([A-Za-z0-9.]+):/,
+  );
+  return match ? match[1].trim() : "";
+}
+
+function extractRoleAgentIds(rawPrompt) {
+  const evaluatorMatch = String(rawPrompt || "").match(/- Evaluator agent id:\s*([A-Za-z0-9.]+)/);
+  const integrationMatch = String(rawPrompt || "").match(
+    /- Integration steward agent id:\s*([A-Za-z0-9.]+)/,
+  );
+  const documentationMatch = String(rawPrompt || "").match(
+    /- Documentation steward agent id:\s*([A-Za-z0-9.]+)/,
+  );
+  return {
+    evaluatorAgentId: evaluatorMatch ? evaluatorMatch[1].trim() : "A0",
+    integrationAgentId: integrationMatch ? integrationMatch[1].trim() : "A8",
+    documentationAgentId: documentationMatch ? documentationMatch[1].trim() : "A9",
+  };
+}
+
+function extractOwnedComponents(rawPrompt) {
+  const lines = String(rawPrompt || "").split(/\r?\n/);
+  const components = [];
+  let inComponents = false;
+  for (const line of lines) {
+    if (/^\s*Components you own in this wave:\s*$/i.test(line)) {
+      inComponents = true;
+      continue;
+    }
+    if (inComponents && /^\s*[A-Za-z][A-Za-z0-9 _/-]*:\s*$/.test(line)) {
+      inComponents = false;
+    }
+    if (!inComponents) {
+      continue;
+    }
+    const bulletMatch = line.match(/^\s*-\s+([a-z0-9._-]+)(?:\s*:\s*([a-z0-9._-]+))?\s*$/i);
+    if (!bulletMatch) {
+      continue;
+    }
+    components.push({
+      componentId: bulletMatch[1],
+      level: bulletMatch[2] || null,
+    });
+  }
+  return components;
+}
+
+function extractDeliverables(promptText) {
+  const out = [];
+  let inFileOwnership = false;
+  for (const line of promptText.split(/\r?\n/)) {
+    if (/^\s*File ownership\b/i.test(line)) {
+      inFileOwnership = true;
+      continue;
+    }
+    if (inFileOwnership && /^\s*[A-Za-z][A-Za-z0-9 _-]*:\s*$/.test(line)) {
+      inFileOwnership = false;
+    }
+    if (inFileOwnership) {
+      const bulletMatch = line.match(/^\s*-\s+(.+?)\s*$/);
+      if (bulletMatch) {
+        const cleaned = bulletMatch[1].replace(/[`"']/g, "").trim();
+        if (
+          cleaned.includes("/") ||
+          /\.(md|mdx|js|mjs|ts|go|json|yaml|yml|sh|sql)$/.test(cleaned)
+        ) {
+          out.push(cleaned);
+          continue;
+        }
+      }
+    }
+    const match = line.match(/^\s*\d+[.)]\s*(.+?)\s*$/);
+    if (!match) {
+      continue;
+    }
+    const cleaned = match[1].replace(/[`"']/g, "").trim();
+    if (cleaned.includes("/") || /\.(md|mdx|js|mjs|ts|go|json|yaml|yml|sh)$/.test(cleaned)) {
+      out.push(cleaned);
+    }
+  }
+  return Array.from(new Set(out));
+}
+
+export function resolveRepoOwnedDeliverablePath(relPath) {
+  if (!relPath || path.isAbsolute(relPath)) {
+    throw new Error(`Unsafe deliverable path: ${String(relPath || "")}`);
+  }
+  const absPath = path.resolve(REPO_ROOT, relPath);
+  const relative = path.relative(REPO_ROOT, absPath);
+  if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error(`Deliverable escapes repo root: ${relPath}`);
+  }
+  return absPath;
+}
+
+function markdownTemplate(relPath, promptText, options = {}) {
+  const requirements = promptText
+    .split(/\r?\n/)
+    .map((line) => line.match(/^\s*-\s+(.+)$/)?.[1]?.trim())
+    .filter(Boolean)
+    .slice(0, 12);
+
+  return [
+    `# ${titleFromPath(relPath)}`,
+    "",
+    "Generated by `wave-local-executor` for smoke-testing the Wave framework.",
+    "",
+    "## Objective",
+    `Create an implementation-ready placeholder for \`${relPath}\` so the local executor path can complete.`,
+    "",
+    "## Scope",
+    ...(requirements.length > 0
+      ? requirements.map((item) => `- ${item}`)
+      : ["- Derived from assigned wave prompt."]),
+    "",
+    ...(options.evaluatorReport ? ["## Verdict", "Verdict: PASS", ""] : []),
+    "## Note",
+    "- Replace this placeholder with real implementation work before relying on it.",
+    "",
+  ].join("\n");
+}
+
+function sourceTemplate(relPath) {
+  return [
+    "// Generated by wave-local-executor for smoke-testing only.",
+    `// Source deliverable: ${relPath}`,
+    "",
+    "export {};",
+    "",
+  ].join("\n");
+}
+
+function writeDeliverable(relPath, promptText, options = {}) {
+  const absPath = resolveRepoOwnedDeliverablePath(relPath);
+  ensureDirectory(path.dirname(absPath));
+  if (fs.existsSync(absPath)) {
+    return "exists";
+  }
+  if (/\.(md|mdx)$/i.test(absPath)) {
+    const evaluatorReport =
+      options.evaluatorAgent === true &&
+      /(?:^|\/)(?:reviews?|.*evaluator).*\.(md|mdx)$/i.test(relPath);
+    fs.writeFileSync(
+      absPath,
+      `${markdownTemplate(relPath, promptText, { evaluatorReport })}\n`,
+      "utf8",
+    );
+    return "created";
+  }
+  fs.writeFileSync(absPath, `${sourceTemplate(relPath)}\n`, "utf8");
+  return "created";
+}
+
+function parseArgs(argv) {
+  const options = { promptFile: null };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--") {
+      continue;
+    }
+    if (arg === "--prompt-file") {
+      options.promptFile = argv[++i] ? path.resolve(REPO_ROOT, argv[i]) : null;
+    } else if (arg === "--help" || arg === "-h") {
+      return { help: true, options };
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+  if (!options.promptFile) {
+    throw new Error("--prompt-file is required");
+  }
+  return { help: false, options };
+}
+
+export function runLocalExecutorCli(argv) {
+  const { help, options } = parseArgs(argv);
+  if (help) {
+    console.log("Usage: pnpm exec wave local --prompt-file <path>");
+    return;
+  }
+  const rawPrompt = fs.readFileSync(options.promptFile, "utf8");
+  const agentId = extractAgentId(rawPrompt);
+  const { evaluatorAgentId, integrationAgentId, documentationAgentId } = extractRoleAgentIds(rawPrompt);
+  const evaluatorAgent = agentId === evaluatorAgentId;
+  const integrationAgent = agentId === integrationAgentId;
+  const ownedComponents = extractOwnedComponents(rawPrompt);
+  const assignedPrompt = extractAssignedPrompt(rawPrompt);
+  const deliverables = extractDeliverables(assignedPrompt);
+  if (deliverables.length === 0) {
+    console.log("[local-executor] no deliverables detected; nothing to do.");
+    if (evaluatorAgent) {
+      console.log(
+        "[wave-gate] architecture=pass integration=pass durability=pass live=pass docs=pass detail=local-executor-no-deliverables",
+      );
+      console.log("[wave-verdict] pass detail=local-executor-no-deliverables");
+    } else if (integrationAgent) {
+      console.log(
+        "[wave-integration] state=ready-for-doc-closure claims=0 conflicts=0 blockers=0 detail=local-executor-no-deliverables",
+      );
+    } else if (agentId === documentationAgentId) {
+      console.log("[wave-doc-closure] state=no-change detail=local-executor-no-deliverables");
+    } else if (agentId) {
+      console.log(
+        "[wave-proof] completion=contract durability=none proof=unit state=met detail=local-executor-no-deliverables",
+      );
+      console.log("[wave-doc-delta] state=none detail=local-executor-no-deliverables");
+      for (const component of ownedComponents) {
+        console.log(
+          `[wave-component] component=${component.componentId} level=${component.level || "repo-landed"} state=met detail=local-executor-no-deliverables`,
+        );
+      }
+    }
+    return;
+  }
+  console.log(`[local-executor] prompt=${path.relative(REPO_ROOT, options.promptFile)}`);
+  console.log(`[local-executor] deliverables=${deliverables.join(", ")}`);
+  for (const deliverable of deliverables) {
+    console.log(
+      `[local-executor] ${writeDeliverable(deliverable, assignedPrompt, { evaluatorAgent })}: ${deliverable}`,
+    );
+  }
+  if (evaluatorAgent) {
+    console.log(
+      "[wave-gate] architecture=pass integration=pass durability=pass live=pass docs=pass detail=local-executor-smoke",
+    );
+    console.log("[wave-verdict] pass detail=local-executor-smoke");
+  } else if (integrationAgent) {
+    console.log(
+      "[wave-integration] state=ready-for-doc-closure claims=0 conflicts=0 blockers=0 detail=local-executor-smoke",
+    );
+  } else if (agentId === documentationAgentId) {
+    console.log("[wave-doc-closure] state=no-change detail=local-executor-smoke");
+  } else if (agentId) {
+    console.log(
+      "[wave-proof] completion=contract durability=none proof=unit state=met detail=local-executor-smoke",
+    );
+    console.log("[wave-doc-delta] state=owned detail=local-executor-smoke");
+    for (const component of ownedComponents) {
+      console.log(
+        `[wave-component] component=${component.componentId} level=${component.level || "repo-landed"} state=met detail=local-executor-smoke`,
+      );
+    }
+  }
+  console.log("[local-executor] completed.");
+}