@chllming/wave-orchestration 0.7.1 → 0.7.3

package/scripts/wave-orchestrator/artifact-schemas.mjs

@@ -403,3 +403,84 @@ export function writeWaveControlDeliveryState(filePath, payload, defaults = {})
 export function cloneArtifactPayload(value) {
   return cloneJson(value);
 }
+
+// ── Wave 4: Surface class metadata and additional schema normalizers ──
+
+export const WAVE_STATE_SCHEMA_VERSION = 1;
+export const TASK_ENTITY_SCHEMA_VERSION = 1;
+export const AGENT_RESULT_ENVELOPE_SCHEMA_VERSION = 1;
+export const RESUME_PLAN_SCHEMA_VERSION = 1;
+export const HUMAN_INPUT_WORKFLOW_SCHEMA_VERSION = 1;
+
+export const SURFACE_CLASS_CANONICAL_EVENT = "canonical-event";
+export const SURFACE_CLASS_CANONICAL_SNAPSHOT = "canonical-snapshot";
+export const SURFACE_CLASS_CACHED_DERIVED = "cached-derived";
+export const SURFACE_CLASS_HUMAN_PROJECTION = "human-projection";
+export const SURFACE_CLASSES = new Set([
+  SURFACE_CLASS_CANONICAL_EVENT,
+  SURFACE_CLASS_CANONICAL_SNAPSHOT,
+  SURFACE_CLASS_CACHED_DERIVED,
+  SURFACE_CLASS_HUMAN_PROJECTION,
+]);
+
+export const WAVE_STATE_KIND = "wave-state-snapshot";
+export const TASK_ENTITY_KIND = "wave-task-entity";
+export const AGENT_RESULT_ENVELOPE_KIND = "agent-result-envelope";
+export const RESUME_PLAN_KIND = "wave-resume-plan";
+export const HUMAN_INPUT_WORKFLOW_KIND = "human-input-workflow-state";
+
+export function normalizeWaveStateSnapshot(payload, defaults = {}) {
+  const source = isPlainObject(payload) ? payload : {};
+  return {
+    schemaVersion: WAVE_STATE_SCHEMA_VERSION,
+    kind: WAVE_STATE_KIND,
+    _meta: { surfaceClass: SURFACE_CLASS_CANONICAL_SNAPSHOT },
+    lane: normalizeText(source.lane, normalizeText(defaults.lane, null)),
+    wave: normalizeInteger(source.wave, normalizeInteger(defaults.wave, null)),
+    ...source,
+    schemaVersion: WAVE_STATE_SCHEMA_VERSION,
+    kind: WAVE_STATE_KIND,
+    _meta: { surfaceClass: SURFACE_CLASS_CANONICAL_SNAPSHOT },
+    generatedAt: normalizeText(source.generatedAt, toIsoTimestamp()),
+  };
+}
+
+export function readWaveStateSnapshot(filePath, defaults = {}) {
+  const payload = readJsonOrNull(filePath);
+  if (!payload) {
+    return null;
+  }
+  return normalizeWaveStateSnapshot(payload, defaults);
+}
+
+export function writeWaveStateSnapshot(filePath, payload, defaults = {}) {
+  const normalized = normalizeWaveStateSnapshot(payload, defaults);
+  writeJsonAtomic(filePath, normalized);
+  return normalized;
+}
+
+export function normalizeAgentResultEnvelope(payload) {
+  const source = isPlainObject(payload) ? payload : {};
+  return {
+    schemaVersion: AGENT_RESULT_ENVELOPE_SCHEMA_VERSION,
+    kind: AGENT_RESULT_ENVELOPE_KIND,
+    _meta: { surfaceClass: SURFACE_CLASS_CANONICAL_SNAPSHOT },
+    ...source,
+    schemaVersion: AGENT_RESULT_ENVELOPE_SCHEMA_VERSION,
+    kind: AGENT_RESULT_ENVELOPE_KIND,
+    _meta: { surfaceClass: SURFACE_CLASS_CANONICAL_SNAPSHOT },
+  };
+}
+
+export function normalizeResumePlan(payload) {
+  const source = isPlainObject(payload) ? payload : {};
+  return {
+    schemaVersion: RESUME_PLAN_SCHEMA_VERSION,
+    kind: RESUME_PLAN_KIND,
+    _meta: { surfaceClass: SURFACE_CLASS_CACHED_DERIVED },
+    ...source,
+    schemaVersion: RESUME_PLAN_SCHEMA_VERSION,
+    kind: RESUME_PLAN_KIND,
+    _meta: { surfaceClass: SURFACE_CLASS_CACHED_DERIVED },
+  };
+}

package/scripts/wave-orchestrator/control-cli.mjs

@@ -315,9 +315,15 @@ function buildLogicalAgents({ lanePaths, wave, tasks, dependencySnapshot, capabi
   return wave.agents.map((agent) => {
     const statusPath = statusPathForAgent(lanePaths, wave, agent);
     const statusRecord = readStatusRecordIfPresent(statusPath);
+    const logPath = path.join(lanePaths.logsDir, `wave-${wave.wave}-${agent.slug}.log`);
     const summary = augmentSummaryWithProofRegistry(
       agent,
-      readAgentExecutionSummary(statusPath),
+      readAgentExecutionSummary(statusPath, {
+        agent,
+        statusPath,
+        statusRecord,
+        logPath: fs.existsSync(logPath) ? logPath : null,
+      }),
       proofRegistry || { entries: [] },
     );
     const proofValidation =

package/scripts/wave-orchestrator/coordination.mjs

@@ -269,6 +269,15 @@ export function buildExecutionPrompt({
         "- Use `clear` only when no unresolved findings or approvals remain. Use `blocked` only when the wave must stop before integration.",
       ]
     : [];
+  const coordinationCommand = [
+    "pnpm exec wave coord post",
+    `--lane ${lane}`,
+    `--wave ${wave}`,
+    `--agent ${agent.agentId}`,
+    '--kind "<request|ack|claim|evidence|decision|blocker|handoff|clarification-request|orchestrator-guidance|resolved-by-policy|human-escalation|human-feedback|integration-summary>"',
+    '--summary "<one-line summary>"',
+    '--detail "<short detail>"',
+  ].join(" ");
   const implementationRequirements =
     ![contQaAgentId, documentationAgentId].includes(agent.agentId) &&
     !isSecurityReviewAgent(agent) &&
@@ -281,7 +290,8 @@ export function buildExecutionPrompt({
                 "- Emit one final structured component marker per owned component: `[wave-component] component=<id> level=<level> state=<met|gap> detail=<short-note>`.",
               ]
             : []),
-          "- If you leave any material architecture, integration, durability, ops, or docs gap, emit `[wave-gap] kind=<architecture|integration|durability|ops|docs> detail=<short-note>` and make the gap explicit instead of implying completion.",
+          "- If the work is incomplete, keep the required proof/doc/component markers and set `state=gap` on the relevant final marker instead of narrating completion.",
+          `- Route unresolved architecture, integration, durability, ops, or docs issues through \`${coordinationCommand}\`. Do not append \`[wave-gap]\` lines after the final implementation markers.`,
         ]
       : [];
   const exitContractLines = agent.exitContract
@@ -305,15 +315,6 @@ export function buildExecutionPrompt({
     '--context "<what you tried, options, and impact>"',
     "--timeout-seconds 30",
   ].join(" ");
-  const coordinationCommand = [
-    "pnpm exec wave coord post",
-    `--lane ${lane}`,
-    `--wave ${wave}`,
-    `--agent ${agent.agentId}`,
-    '--kind "<request|ack|claim|evidence|decision|blocker|handoff|clarification-request|orchestrator-guidance|resolved-by-policy|human-escalation|human-feedback|integration-summary>"',
-    '--summary "<one-line summary>"',
-    '--detail "<short detail>"',
-  ].join(" ");
   const context7Selection = context7?.selection || agent?.context7Resolved || null;
   const executorId = agent?.executorResolved?.id || "default";
   const context7LibrarySummary =

package/scripts/wave-orchestrator/human-input-workflow.mjs

@@ -0,0 +1,289 @@
+import { toIsoTimestamp } from "./shared.mjs";
+
+// ── Human Input Workflow State Machine ──
+//
+// States: open -> pending -> answered -> resolved
+//                         -> escalated -> resolved
+
+export const HUMAN_INPUT_STATES = new Set([
+  "open",
+  "pending",
+  "answered",
+  "escalated",
+  "resolved",
+]);
+
+export const HUMAN_INPUT_VALID_TRANSITIONS = {
+  open: ["pending", "escalated", "resolved"],
+  pending: ["answered", "escalated", "resolved"],
+  answered: ["resolved"],
+  escalated: ["answered", "resolved"],
+  resolved: [],
+};
+
+const BLOCKING_STATES = new Set(["open", "pending", "escalated"]);
+
+const DEFAULT_TIMEOUT_POLICY = {
+  maxWaitMs: 300000,
+  escalateAfterMs: 120000,
+};
+
+const DEFAULT_REROUTE_POLICY = {
+  rerouteOnTimeout: true,
+  rerouteTo: "operator",
+};
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function normalizeText(value, fallback = null) {
+  const normalized = String(value ?? "").trim();
+  return normalized || fallback;
+}
+
+export function normalizeHumanInputRequest(request, defaults = {}) {
+  const source = isPlainObject(request) ? request : {};
+  const defaultSource = isPlainObject(defaults) ? defaults : {};
+  const now = toIsoTimestamp();
+
+  const timeoutPolicy = isPlainObject(source.timeoutPolicy)
+    ? {
+        maxWaitMs: Number.isFinite(source.timeoutPolicy.maxWaitMs)
+          ? source.timeoutPolicy.maxWaitMs
+          : DEFAULT_TIMEOUT_POLICY.maxWaitMs,
+        escalateAfterMs: Number.isFinite(source.timeoutPolicy.escalateAfterMs)
+          ? source.timeoutPolicy.escalateAfterMs
+          : DEFAULT_TIMEOUT_POLICY.escalateAfterMs,
+      }
+    : { ...DEFAULT_TIMEOUT_POLICY };
+
+  const reroutePolicy = isPlainObject(source.reroutePolicy)
+    ? {
+        rerouteOnTimeout: source.reroutePolicy.rerouteOnTimeout !== false,
+        rerouteTo: normalizeText(source.reroutePolicy.rerouteTo, DEFAULT_REROUTE_POLICY.rerouteTo),
+      }
+    : { ...DEFAULT_REROUTE_POLICY };
+
+  const rawState = normalizeText(source.state, normalizeText(defaultSource.state, "open"));
+  const state = HUMAN_INPUT_STATES.has(rawState) ? rawState : "open";
+
+  return {
+    requestId: normalizeText(source.requestId, normalizeText(defaultSource.requestId, null)),
+    kind: normalizeText(source.kind, normalizeText(defaultSource.kind, "human-input")),
+    state,
+    title: normalizeText(source.title, normalizeText(defaultSource.title, null)),
+    detail: normalizeText(source.detail, normalizeText(defaultSource.detail, null)),
+    requestedBy: normalizeText(source.requestedBy, normalizeText(defaultSource.requestedBy, null)),
+    assignedTo: normalizeText(source.assignedTo, normalizeText(defaultSource.assignedTo, null)),
+    timeoutPolicy,
+    reroutePolicy,
+    createdAt: normalizeText(source.createdAt, normalizeText(defaultSource.createdAt, now)),
+    updatedAt: normalizeText(source.updatedAt, normalizeText(defaultSource.updatedAt, now)),
+    answeredAt: normalizeText(source.answeredAt, null),
+    resolvedAt: normalizeText(source.resolvedAt, null),
+    escalatedAt: normalizeText(source.escalatedAt, null),
+    answer: normalizeText(source.answer, null),
+    resolution: normalizeText(source.resolution, null),
+  };
+}
+
+export function transitionHumanInputState(currentState, targetState) {
+  if (!HUMAN_INPUT_STATES.has(currentState)) {
+    throw new Error(`Invalid current state: ${currentState}`);
+  }
+  if (!HUMAN_INPUT_STATES.has(targetState)) {
+    throw new Error(`Invalid target state: ${targetState}`);
+  }
+  const allowed = HUMAN_INPUT_VALID_TRANSITIONS[currentState];
+  if (!allowed || !allowed.includes(targetState)) {
+    throw new Error(
+      `Invalid transition from "${currentState}" to "${targetState}". Allowed: [${(allowed || []).join(", ")}]`,
+    );
+  }
+  return targetState;
+}
+
+export function isHumanInputBlocking(request) {
+  const source = isPlainObject(request) ? request : {};
+  const state = normalizeText(source.state, "open");
+  return BLOCKING_STATES.has(state);
+}
+
+export function buildHumanInputRequests(coordinationState, feedbackRequests, options = {}) {
+  const results = [];
+  const coordState = isPlainObject(coordinationState) ? coordinationState : {};
+  const feedbackList = Array.isArray(feedbackRequests) ? feedbackRequests : [];
+  const now = toIsoTimestamp();
+
+  // Process clarification-request records from coordination state
+  const clarifications = Array.isArray(coordState.clarifications)
+    ? coordState.clarifications
+    : [];
+  for (const record of clarifications) {
+    if (!isPlainObject(record)) continue;
+    const kind = normalizeText(record.kind, null);
+    if (
+      kind !== "clarification-request" &&
+      kind !== "human-escalation" &&
+      kind !== "human-feedback"
+    ) {
+      continue;
+    }
+    const mappedKind =
+      kind === "clarification-request"
+        ? "clarification"
+        : kind === "human-escalation"
+          ? "escalation"
+          : "feedback";
+    const rawStatus = normalizeText(record.status, "open");
+    let mappedState = "open";
+    if (rawStatus === "in_progress" || rawStatus === "pending") {
+      mappedState = "pending";
+    } else if (rawStatus === "resolved" || rawStatus === "closed") {
+      mappedState = "resolved";
+    } else if (rawStatus === "answered") {
+      mappedState = "answered";
+    }
+    results.push(
+      normalizeHumanInputRequest({
+        requestId: normalizeText(record.id, null),
+        kind: mappedKind,
+        state: mappedState,
+        title: normalizeText(record.summary, null),
+        detail: normalizeText(record.detail, null),
+        requestedBy: normalizeText(record.agentId, null),
+        assignedTo: null,
+        createdAt: normalizeText(record.createdAt, now),
+        updatedAt: normalizeText(record.updatedAt, now),
+      }),
+    );
+  }
+
+  // Process human escalations from coordination state
+  const humanEscalations = Array.isArray(coordState.humanEscalations)
+    ? coordState.humanEscalations
+    : [];
+  for (const record of humanEscalations) {
+    if (!isPlainObject(record)) continue;
+    const rawStatus = normalizeText(record.status, "open");
+    let mappedState = "escalated";
+    if (rawStatus === "resolved" || rawStatus === "closed") {
+      mappedState = "resolved";
+    } else if (rawStatus === "answered") {
+      mappedState = "answered";
+    }
+    results.push(
+      normalizeHumanInputRequest({
+        requestId: normalizeText(record.id, null),
+        kind: "escalation",
+        state: mappedState,
+        title: normalizeText(record.summary, null),
+        detail: normalizeText(record.detail, null),
+        requestedBy: normalizeText(record.agentId, null),
+        assignedTo: "operator",
+        createdAt: normalizeText(record.createdAt, now),
+        updatedAt: normalizeText(record.updatedAt, now),
+        escalatedAt: normalizeText(record.createdAt, now),
+      }),
+    );
+  }
+
+  // Process feedback requests
+  for (const record of feedbackList) {
+    if (!isPlainObject(record)) continue;
+    const rawStatus = normalizeText(record.status, "pending");
+    let mappedState = "pending";
+    if (rawStatus === "answered") {
+      mappedState = "answered";
+    } else if (rawStatus === "resolved" || rawStatus === "closed") {
+      mappedState = "resolved";
+    }
+    results.push(
+      normalizeHumanInputRequest({
+        requestId: normalizeText(record.id, null),
+        kind: "feedback",
+        state: mappedState,
+        title: normalizeText(record.question, null),
+        detail: normalizeText(record.context, null),
+        requestedBy: normalizeText(record.agentId, null),
+        assignedTo: "operator",
+        createdAt: normalizeText(record.createdAt, now),
+        updatedAt: normalizeText(record.updatedAt, now),
+        answeredAt: normalizeText(record.response?.answeredAt, null),
+        answer: normalizeText(record.response?.text, null),
+      }),
+    );
+  }
+
+  return results;
+}
+
+export function evaluateHumanInputTimeout(request, now = Date.now()) {
+  const source = isPlainObject(request) ? request : {};
+  const createdAtMs = Date.parse(source.createdAt || "");
+  if (!Number.isFinite(createdAtMs)) {
+    return { expired: false, shouldEscalate: false, elapsedMs: 0 };
+  }
+  const elapsedMs = Math.max(0, now - createdAtMs);
+  const policy = isPlainObject(source.timeoutPolicy)
+    ? source.timeoutPolicy
+    : DEFAULT_TIMEOUT_POLICY;
+  const maxWaitMs = Number.isFinite(policy.maxWaitMs)
+    ? policy.maxWaitMs
+    : DEFAULT_TIMEOUT_POLICY.maxWaitMs;
+  const escalateAfterMs = Number.isFinite(policy.escalateAfterMs)
+    ? policy.escalateAfterMs
+    : DEFAULT_TIMEOUT_POLICY.escalateAfterMs;
+  const expired = elapsedMs >= maxWaitMs;
+  const shouldEscalate = elapsedMs >= escalateAfterMs;
+  return { expired, shouldEscalate, elapsedMs };
+}
+
+export function computeHumanInputMetrics(requests) {
+  const list = Array.isArray(requests) ? requests : [];
+  const counts = { open: 0, pending: 0, answered: 0, escalated: 0, resolved: 0 };
+  let blocking = 0;
+  let overdueCount = 0;
+  let totalResolutionMs = 0;
+  let resolvedWithTimesCount = 0;
+
+  for (const request of list) {
+    const source = isPlainObject(request) ? request : {};
+    const state = normalizeText(source.state, "open");
+    if (state in counts) {
+      counts[state] += 1;
+    }
+    if (BLOCKING_STATES.has(state)) {
+      blocking += 1;
+    }
+    // Check overdue based on timeout policy
+    const timeout = evaluateHumanInputTimeout(source);
+    if (timeout.expired && BLOCKING_STATES.has(state)) {
+      overdueCount += 1;
+    }
+    // Compute resolution time for resolved requests
+    if (state === "resolved" && source.createdAt && source.resolvedAt) {
+      const createdMs = Date.parse(source.createdAt);
+      const resolvedMs = Date.parse(source.resolvedAt);
+      if (Number.isFinite(createdMs) && Number.isFinite(resolvedMs) && resolvedMs >= createdMs) {
+        totalResolutionMs += resolvedMs - createdMs;
+        resolvedWithTimesCount += 1;
+      }
+    }
+  }
+
+  return {
+    total: list.length,
+    open: counts.open,
+    pending: counts.pending,
+    answered: counts.answered,
+    escalated: counts.escalated,
+    resolved: counts.resolved,
+    blocking,
+    overdueCount,
+    avgResolutionMs: resolvedWithTimesCount > 0
+      ? Math.round(totalResolutionMs / resolvedWithTimesCount)
+      : null,
+  };
+}

package/scripts/wave-orchestrator/install.mjs

@@ -198,6 +198,28 @@ function copyTemplateFile(relPath) {
     throw new Error(`Missing packaged template: ${relPath}`);
   }
   ensureDirectory(path.dirname(targetPath));
+  if (relPath === "docs/plans/component-cutover-matrix.json") {
+    const payload = readJsonOrNull(sourcePath);
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+      throw new Error(`Invalid packaged template JSON: ${relPath}`);
+    }
+    const components = Object.fromEntries(
+      Object.entries(payload.components || {}).map(([componentId, component]) => [
+        componentId,
+        {
+          ...component,
+          promotions: Array.isArray(component?.promotions)
+            ? component.promotions.filter((entry) => Number(entry?.wave) === 0)
+            : [],
+        },
+      ]),
+    );
+    writeJsonAtomic(targetPath, {
+      ...payload,
+      components,
+    });
+    return targetPath;
+  }
   fs.copyFileSync(sourcePath, targetPath);
   return targetPath;
 }