@chllming/wave-orchestration 0.9.13 → 0.9.15

package/scripts/wave-orchestrator/dashboard-state.mjs

@@ -124,6 +124,24 @@ export function normalizePhaseState(value) {
     : null;
 }
 
+function deriveWaveProjectionTriplet(status) {
+  const normalized = String(status || "").trim().toLowerCase();
+  if (["running", "retrying"].includes(normalized)) {
+    return { executionState: "active", closureState: "evaluating", controllerState: "active" };
+  }
+  if (normalized === "completed") {
+    return { executionState: "settled", closureState: "passed", controllerState: "idle" };
+  }
+  if (["blocked", "failed", "timed_out"].includes(normalized)) {
+    return {
+      executionState: "settled",
+      closureState: "blocked",
+      controllerState: normalized === "blocked" ? "relaunch-planned" : "stale",
+    };
+  }
+  return { executionState: "pending", closureState: "pending", controllerState: "idle" };
+}
+
 export function buildWaveDashboardState({
   lane,
   wave,
@@ -134,12 +152,16 @@ export function buildWaveDashboardState({
   agentRuns,
 }) {
   const now = toIsoTimestamp();
+  const projectionStates = deriveWaveProjectionTriplet("running");
   return normalizeWaveDashboardState({
     lane,
     wave,
     waveFile,
     runTag,
     status: "running",
+    executionState: projectionStates.executionState,
+    closureState: projectionStates.closureState,
+    controllerState: projectionStates.controllerState,
     attempt: 0,
     maxAttempts,
     startedAt: now,
@@ -192,10 +214,14 @@ export function buildGlobalDashboardState({
   feedbackRequestsDir,
 }) {
   const now = toIsoTimestamp();
+  const projectionStates = deriveWaveProjectionTriplet("running");
   return normalizeGlobalDashboardState({
     lane,
     runId: Math.random().toString(16).slice(2, 14),
     status: "running",
+    executionState: projectionStates.executionState,
+    closureState: projectionStates.closureState,
+    controllerState: projectionStates.controllerState,
     startedAt: now,
     updatedAt: now,
     options: {
@@ -223,6 +249,9 @@ export function buildGlobalDashboardState({
       wave: wave.wave,
       waveFile: wave.file,
       status: "pending",
+      executionState: "pending",
+      closureState: "pending",
+      controllerState: "idle",
       attempt: 0,
       maxAttempts: options.maxRetriesPerWave + 1,
       dashboardPath: path.relative(
@@ -260,8 +289,12 @@ export function buildGlobalDashboardState({
 
 export function writeWaveDashboard(dashboardPath, state) {
   ensureDirectory(path.dirname(dashboardPath));
+  const projectionStates = deriveWaveProjectionTriplet(state?.status);
   const normalized = normalizeWaveDashboardState({
     ...state,
+    executionState: state?.executionState || projectionStates.executionState,
+    closureState: state?.closureState || projectionStates.closureState,
+    controllerState: state?.controllerState || projectionStates.controllerState,
     updatedAt: toIsoTimestamp(),
   });
   Object.assign(state, normalized);
@@ -270,8 +303,12 @@ export function writeWaveDashboard(dashboardPath, state) {
 
 export function writeGlobalDashboard(globalDashboardPath, state) {
   ensureDirectory(path.dirname(globalDashboardPath));
+  const projectionStates = deriveWaveProjectionTriplet(state?.status);
   const normalized = normalizeGlobalDashboardState({
     ...state,
+    executionState: state?.executionState || projectionStates.executionState,
+    closureState: state?.closureState || projectionStates.closureState,
+    controllerState: state?.controllerState || projectionStates.controllerState,
     updatedAt: toIsoTimestamp(),
   });
   Object.assign(state, normalized);
@@ -316,6 +353,9 @@ export function syncGlobalWaveFromWaveDashboard(globalState, waveDashboard) {
     return;
   }
   entry.status = waveDashboard.status;
+  entry.executionState = waveDashboard.executionState || null;
+  entry.closureState = waveDashboard.closureState || null;
+  entry.controllerState = waveDashboard.controllerState || null;
   entry.attempt = waveDashboard.attempt;
   entry.startedAt = waveDashboard.startedAt;
   if (WAVE_TERMINAL_STATES.has(waveDashboard.status)) {

package/scripts/wave-orchestrator/derived-state-engine.mjs

@@ -430,6 +430,9 @@ function buildIntegrationEvidence({
     ) {
       const validation = validateImplementationSummary(agent, summary);
       if (!validation.ok) {
+        if (validation.failureClass === "transport-failure" && validation.eligibleForAdjudication) {
+          continue;
+        }
         const entry = summarizeGap(agent.agentId, validation.detail, "Implementation validation failed.");
         if (["missing-doc-delta", "doc-impact-gap", "invalid-doc-delta-format"].includes(validation.statusCode)) {
           docGapEntries.push(entry);

package/scripts/wave-orchestrator/gate-engine.mjs

@@ -57,6 +57,11 @@ import {
   evaluateDocumentationAutoClosure,
   evaluateInferredIntegrationClosure,
 } from "./closure-policy.mjs";
+import {
+  evaluateClosureAdjudication,
+  persistClosureAdjudication,
+  closureAdjudicationPath,
+} from "./closure-adjudicator.mjs";
 
 function contradictionList(value) {
   if (value instanceof Map) {
@@ -142,6 +147,34 @@ function validateEnvelopeForRun(runInfo, envelope, options = {}) {
   };
 }
 
+function adjudicatedGateResult(validation, runInfo, summary, adjudication, adjudicationPathValue = null) {
+  if (adjudication.status === "pass") {
+    return {
+      ok: true,
+      agentId: runInfo.agent.agentId,
+      statusCode: validation.statusCode,
+      detail: adjudication.detail,
+      logPath: summary?.logPath || path.relative(REPO_ROOT, runInfo.logPath),
+      adjudicated: true,
+      adjudicationStatus: adjudication.status,
+      adjudicationArtifactPath: adjudicationPathValue ? path.relative(REPO_ROOT, adjudicationPathValue) : null,
+      failureClass: validation.failureClass || null,
+    };
+  }
+  return {
+    ok: false,
+    agentId: runInfo.agent.agentId,
+    statusCode: adjudication.status === "ambiguous" ? "awaiting-adjudication" : validation.statusCode,
+    detail: adjudication.detail || validation.detail,
+    logPath: summary?.logPath || path.relative(REPO_ROOT, runInfo.logPath),
+    adjudicated: true,
+    adjudicationStatus: adjudication.status,
+    adjudicationArtifactPath: adjudicationPathValue ? path.relative(REPO_ROOT, adjudicationPathValue) : null,
+    failureClass: validation.failureClass || null,
+    eligibleForAdjudication: validation.eligibleForAdjudication === true,
+  };
+}
+
 
 // --- Laddered gate modes (0.9.4) ---
 export function resolveGateMode(waveNumber, thresholds) {
@@ -612,13 +645,14 @@ export function readWaveImplementationGate(wave, agentRuns, options = {}) {
         logPath: path.relative(REPO_ROOT, runInfo.logPath),
       };
     }
+    const statusRecord = runInfo?.statusPath ? readStatusRecordIfPresent(runInfo.statusPath) : null;
     const summary = envelopeResult.valid
       ? projectLegacySummaryFromEnvelope(
           envelopeResult.envelope,
           buildEnvelopeReadOptions(
             runInfo,
             wave,
-            runInfo?.statusPath ? readStatusRecordIfPresent(runInfo.statusPath) : null,
+            statusRecord,
             resolveRunReportPath(wave, runInfo, options),
           ),
         )
@@ -628,12 +662,45 @@ export function readWaveImplementationGate(wave, agentRuns, options = {}) {
       });
     const validation = validateImplementationSummary(runInfo.agent, summary);
     if (!validation.ok) {
+      if (validation.eligibleForAdjudication) {
+        const adjudication = evaluateClosureAdjudication({
+          wave,
+          lanePaths: options.lanePaths || null,
+          gate: validation,
+          summary,
+          derivedState: options.derivedState || null,
+          agentRun: runInfo,
+          envelope: envelopeResult.valid ? envelopeResult.envelope : null,
+        });
+        let adjudicationArtifactPath = null;
+        if (options.lanePaths?.statusDir) {
+          const persisted = persistClosureAdjudication({
+            lanePaths: options.lanePaths,
+            waveNumber: wave.wave,
+            attempt: statusRecord?.attempt || envelopeResult.envelope?.attempt || 1,
+            agentId: runInfo.agent.agentId,
+            payload: {
+              status: adjudication.status,
+              failureClass: validation.failureClass,
+              reason: adjudication.reason,
+              detail: adjudication.detail,
+              evidence: adjudication.evidence,
+              synthesizedSignals: adjudication.synthesizedSignals,
+            },
+          });
+          adjudicationArtifactPath = persisted.filePath;
+        }
+        return adjudicatedGateResult(validation, runInfo, summary, adjudication, adjudicationArtifactPath);
+      }
       return {
         ok: false,
         agentId: runInfo.agent.agentId,
         statusCode: validation.statusCode,
         detail: validation.detail,
         logPath: summary?.logPath || path.relative(REPO_ROOT, runInfo.logPath),
+        failureClass: validation.failureClass || null,
+        eligibleForAdjudication: validation.eligibleForAdjudication === true,
+        adjudicationHint: validation.adjudicationHint || null,
       };
     }
   }
@@ -922,7 +989,29 @@ export function readWaveDocumentationGate(wave, agentRuns, options = {}) {
       mode,
       securityRolePromptPath: options.securityRolePromptPath,
     });
-  const validation = validateDocumentationClosureSummary(docRun.agent, summary);
+  const validation = validateDocumentationClosureSummary(docRun.agent, summary, {
+    allowFallbackOnEmptyRun: true,
+  });
+  // Fallback: when doc steward had an empty run but integration/QA passed,
+  // auto-close instead of blocking the wave.
+  if (!validation.ok && validation.eligibleForFallback) {
+    const integrationSummary = options.derivedState?.integrationSummary;
+    const integrationReady =
+      integrationSummary?.recommendation === "ready-for-doc-closure";
+    const contQaPassed =
+      options.derivedState?.ledger?.contQa?.verdict === "pass" ||
+      options.derivedState?.ledger?.contQa?.verdict === "PASS";
+    if (integrationReady || contQaPassed) {
+      return {
+        ok: true,
+        agentId: docRun.agent.agentId,
+        statusCode: "fallback-auto-closed",
+        detail: `Documentation steward ${docRun.agent.agentId} had an empty run. Auto-closed because ${integrationReady ? "integration is ready-for-doc-closure" : "cont-QA passed"}.`,
+        logPath: summary?.logPath || path.relative(REPO_ROOT, docRun.logPath),
+        docClosureState: "no-change",
+      };
+    }
+  }
   return {
     ok: validation.ok,
     agentId: docRun.agent.agentId,
@@ -1311,12 +1400,37 @@ export function readWaveImplementationGatePure(wave, agentResults, options = {})
     const summary = agentResults?.[agent.agentId] || null;
     const validation = validateImplementationSummary(agent, summary);
     if (!validation.ok) {
+      if (validation.eligibleForAdjudication) {
+        const adjudication = evaluateClosureAdjudication({
+          wave,
+          lanePaths: options.lanePaths || null,
+          gate: validation,
+          summary,
+          derivedState: options.derivedState || null,
+          agentRun: { agent, logPath: summary?.logPath ? path.resolve(REPO_ROOT, summary.logPath) : null },
+          envelope: null,
+        });
+        return {
+          ok: adjudication.status === "pass",
+          agentId: agent.agentId,
+          statusCode: adjudication.status === "ambiguous" ? "awaiting-adjudication" : validation.statusCode,
+          detail: adjudication.detail || validation.detail,
+          logPath: summary?.logPath || null,
+          adjudicated: true,
+          adjudicationStatus: adjudication.status,
+          failureClass: validation.failureClass || null,
+          eligibleForAdjudication: true,
+        };
+      }
       return {
         ok: false,
         agentId: agent.agentId,
         statusCode: validation.statusCode,
         detail: validation.detail,
         logPath: summary?.logPath || null,
+        failureClass: validation.failureClass || null,
+        eligibleForAdjudication: validation.eligibleForAdjudication === true,
+        adjudicationHint: validation.adjudicationHint || null,
       };
     }
   }
@@ -1501,7 +1615,30 @@ export function readWaveDocumentationGatePure(wave, agentResults, options = {})
   }
   const summary = agentResults?.[documentationAgentId] || null;
   const agent = { agentId: documentationAgentId };
-  const validation = validateDocumentationClosureSummary(agent, summary);
+  const validation = validateDocumentationClosureSummary(agent, summary, {
+    allowFallbackOnEmptyRun: true,
+  });
+  // When the doc steward had an empty run (broker collision, no output) but
+  // integration is already ready-for-doc-closure, auto-close documentation
+  // instead of failing the entire wave.
+  if (!validation.ok && validation.eligibleForFallback) {
+    const integrationSummary = options.derivedState?.integrationSummary;
+    const integrationReady =
+      integrationSummary?.recommendation === "ready-for-doc-closure";
+    const contQaPassed =
+      options.derivedState?.ledger?.contQa?.verdict === "pass" ||
+      options.derivedState?.ledger?.contQa?.verdict === "PASS";
+    if (integrationReady || contQaPassed) {
+      return {
+        ok: true,
+        agentId: documentationAgentId,
+        statusCode: "fallback-auto-closed",
+        detail: `Documentation steward ${documentationAgentId} had an empty run. Auto-closed because ${integrationReady ? "integration is ready-for-doc-closure" : "cont-QA passed"}.`,
+        logPath: summary?.logPath || null,
+        docClosureState: "no-change",
+      };
+    }
+  }
   return { ok: validation.ok, agentId: documentationAgentId, statusCode: validation.statusCode,
     detail: validation.detail, logPath: summary?.logPath || null };
 }

package/scripts/wave-orchestrator/install.mjs

@@ -69,7 +69,7 @@ export const STARTER_TEMPLATE_PATHS = [
   "docs/guides/author-and-run-waves.md",
   "docs/guides/monorepo-projects.md",
   "docs/guides/planner.md",
-  "docs/guides/recommendations-0.9.13.md",
+  "docs/guides/recommendations-0.9.15.md",
   "docs/guides/sandboxed-environments.md",
   "docs/guides/signal-wrappers.md",
   "docs/guides/terminal-surfaces.md",

package/scripts/wave-orchestrator/launcher.mjs

@@ -715,6 +715,12 @@ function failuresAreRecoverable(failures) {
   return Array.isArray(failures) && failures.length > 0 && failures.every((failure) => failure?.recoverable);
 }
 
+function failuresAwaitAdjudication(failures) {
+  return Array.isArray(failures) && failures.length > 0 && failures.every(
+    (failure) => String(failure?.statusCode || "").trim().toLowerCase() === "awaiting-adjudication",
+  );
+}
+
 function appendRepairCoordinationRequests({
   coordinationLogPath,
   lanePaths,
@@ -771,16 +777,23 @@ export async function runLauncherCli(argv) {
   const projectId = options.project || config.defaultProject;
   if (!readProjectProfile({ config, project: projectId })) {
     const { stderr: stderrStream } = await import("node:process");
-    stderrStream.write(
-      "\n  No project profile found — running first-time setup.\n" +
-        "  You can re-run this later with: wave project setup\n\n",
-    );
-    const { runPlannerCli } = await import("./planner.mjs");
-    await runPlannerCli(["project", "setup", ...(projectId ? ["--project", projectId] : [])]);
-    // Re-read the terminal surface from the newly created profile.
-    const freshProfile = readProjectProfile({ config, project: projectId });
-    if (freshProfile) {
-      options.terminalSurface = resolveDefaultTerminalSurface(freshProfile);
+    if (options.dryRun) {
+      stderrStream.write(
+        "\n  No project profile found — continuing dry-run with config defaults.\n" +
+          "  Live launches will still prompt for first-time setup, or you can run: wave project setup\n\n",
+      );
+    } else {
+      stderrStream.write(
+        "\n  No project profile found — running first-time setup.\n" +
+          "  You can re-run this later with: wave project setup\n\n",
+      );
+      const { runPlannerCli } = await import("./planner.mjs");
+      await runPlannerCli(["project", "setup", ...(projectId ? ["--project", projectId] : [])]);
+      // Re-read the terminal surface from the newly created profile.
+      const freshProfile = readProjectProfile({ config, project: projectId });
+      if (freshProfile) {
+        options.terminalSurface = resolveDefaultTerminalSurface(freshProfile);
+      }
     }
   }
 
@@ -1907,6 +1920,8 @@ export async function runLauncherCli(argv) {
             if (failures.length === 0) {
               const implementationGate = readWaveImplementationGate(wave, agentRuns, {
                 securityRolePromptPath: lanePaths.securityRolePromptPath,
+                lanePaths,
+                derivedState,
               });
               if (!implementationGate.ok) {
                 failures = [
@@ -2449,6 +2464,30 @@ export async function runLauncherCli(argv) {
             throw error;
           }
 
+          if (failuresAwaitAdjudication(failures)) {
+            clearWaveRelaunchPlan(lanePaths, wave.wave);
+            dashboardState.status = "blocked";
+            for (const failure of failures) {
+              setWaveDashboardAgent(dashboardState, failure.agentId, {
+                state: "failed",
+                detail: failure.detail || "Closure is awaiting deterministic adjudication.",
+              });
+            }
+            flushDashboards();
+            appendCoordination({
+              event: "wave_adjudication_pending",
+              waves: [wave.wave],
+              status: "blocked",
+              details: failures.map((failure) => `${failure.agentId || "wave"}:${failure.statusCode}`).join(", "),
+              actionRequested: `Lane ${lanePaths.lane} owners should inspect the persisted closure adjudication artifact before any rerun decision.`,
+            });
+            const error = new Error(
+              `Wave ${wave.wave} is waiting on deterministic closure adjudication; no retry was queued.`,
+            );
+            error.exitCode = 43;
+            throw error;
+          }
+
           const failedAgentIds = new Set(failures.map((failure) => failure.agentId));
           const failedList = Array.from(failedAgentIds).join(", ");
           recordAttemptState(lanePaths, wave.wave, attempt, "failed", {

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

@@ -0,0 +1,271 @@
+import fs from "node:fs";
+import path from "node:path";
+import { ensureDirectory } from "./shared.mjs";
+import {
+  EXIT_CONTRACT_COMPLETION_VALUES,
+  EXIT_CONTRACT_DURABILITY_VALUES,
+  EXIT_CONTRACT_PROOF_VALUES,
+  EXIT_CONTRACT_DOC_IMPACT_VALUES,
+} from "./agent-state.mjs";
+import { parseStructuredSignalCandidate } from "./structured-signal-parser.mjs";
+
+const PROOF_STATES = ["met", "complete", "gap"];
+const DOC_CLOSURE_STATES = ["closed", "no-change", "delta"];
+const INTEGRATION_STATES = ["ready-for-doc-closure", "needs-more-work"];
+const COMPONENT_ID_REGEX = /^[a-z0-9._-]+$/;
+const COMPONENT_LEVEL_REGEX = /^[a-z0-9._-]+$/;
+const UNSAFE_KEY_VALUE_FRAGMENT_REGEX = /(^|\s)[a-z][a-z0-9_-]*=/i;
+const PARSER_KIND_BY_SIGNAL_KIND = {
+  proof: "proof",
+  "doc-delta": "docDelta",
+  component: "component",
+  integration: "integration",
+  "doc-closure": "docClosure",
+};
+
+function printUsage() {
+  console.log(`Usage:
+  wave signal proof --completion <level> --durability <level> --proof <level> --state <met|complete|gap> [--detail <text>] [--json] [--append-file <path>]
+  wave signal doc-delta --state <none|owned|shared-plan> [--path <file> ...] [--detail <text>] [--json] [--append-file <path>]
+  wave signal component --id <component> --level <level> --state <met|complete|gap> [--detail <text>] [--json] [--append-file <path>]
+  wave signal integration --state <ready-for-doc-closure|needs-more-work> --claims <n> --conflicts <n> --blockers <n> [--detail <text>] [--json] [--append-file <path>]
+  wave signal doc-closure --state <closed|no-change|delta> [--path <file> ...] [--detail <text>] [--json] [--append-file <path>]
+`);
+}
+
+function normalizeState(value) {
+  return String(value || "").trim().toLowerCase() === "complete" ? "met" : String(value || "").trim();
+}
+
+function cleanText(value) {
+  return String(value || "").trim();
+}
+
+function validateAllowedValue(label, value, allowedValues) {
+  const normalized = cleanText(value).toLowerCase();
+  if (!allowedValues.includes(normalized)) {
+    throw new Error(`${label} must be one of: ${allowedValues.join(", ")}`);
+  }
+  return normalized;
+}
+
+function validateSafeField(label, value, { allowCommas = true } = {}) {
+  const normalized = cleanText(value);
+  if (!normalized) {
+    return normalized;
+  }
+  if (/[\r\n]/.test(normalized)) {
+    throw new Error(`${label} cannot contain newlines`);
+  }
+  if (!allowCommas && normalized.includes(",")) {
+    throw new Error(`${label} cannot contain commas`);
+  }
+  if (UNSAFE_KEY_VALUE_FRAGMENT_REGEX.test(normalized)) {
+    throw new Error(`${label} cannot contain embedded key=value fragments`);
+  }
+  return normalized;
+}
+
+function validatePathList(paths) {
+  return paths.map((item, index) =>
+    validateSafeField(`path ${index + 1}`, item, { allowCommas: false }),
+  );
+}
+
+function parseArgs(argv) {
+  const kind = String(argv[0] || "").trim().toLowerCase();
+  const options = {
+    completion: "",
+    durability: "",
+    proof: "",
+    state: "",
+    detail: "",
+    componentId: "",
+    level: "",
+    paths: [],
+    claims: "0",
+    conflicts: "0",
+    blockers: "0",
+    appendFile: "",
+    json: false,
+  };
+  for (let index = 1; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--completion") {
+      options.completion = String(argv[++index] || "").trim();
+    } else if (arg === "--durability") {
+      options.durability = String(argv[++index] || "").trim();
+    } else if (arg === "--proof") {
+      options.proof = String(argv[++index] || "").trim();
+    } else if (arg === "--state") {
+      options.state = String(argv[++index] || "").trim();
+    } else if (arg === "--detail") {
+      options.detail = String(argv[++index] || "").trim();
+    } else if (arg === "--id") {
+      options.componentId = String(argv[++index] || "").trim();
+    } else if (arg === "--level") {
+      options.level = String(argv[++index] || "").trim();
+    } else if (arg === "--path") {
+      options.paths.push(String(argv[++index] || "").trim());
+    } else if (arg === "--claims") {
+      options.claims = String(argv[++index] || "0").trim();
+    } else if (arg === "--conflicts") {
+      options.conflicts = String(argv[++index] || "0").trim();
+    } else if (arg === "--blockers") {
+      options.blockers = String(argv[++index] || "0").trim();
+    } else if (arg === "--append-file") {
+      options.appendFile = String(argv[++index] || "").trim();
+    } else if (arg === "--json") {
+      options.json = true;
+    } else if (arg === "--help" || arg === "-h") {
+      return { help: true, kind, options };
+    } else if (arg) {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+  return { help: false, kind, options };
+}
+
+function buildLine(kind, options) {
+  if (kind === "proof") {
+    return [
+      "[wave-proof]",
+      `completion=${options.completion}`,
+      `durability=${options.durability}`,
+      `proof=${options.proof}`,
+      `state=${normalizeState(options.state)}`,
+      ...(options.detail ? [`detail=${options.detail}`] : []),
+    ].join(" ");
+  }
+  if (kind === "doc-delta") {
+    return [
+      "[wave-doc-delta]",
+      `state=${options.state}`,
+      ...(options.paths.length > 0 ? [`paths=${options.paths.join(",")}`] : []),
+      ...(options.detail ? [`detail=${options.detail}`] : []),
+    ].join(" ");
+  }
+  if (kind === "component") {
+    return [
+      "[wave-component]",
+      `component=${options.componentId}`,
+      `level=${options.level}`,
+      `state=${normalizeState(options.state)}`,
+      ...(options.detail ? [`detail=${options.detail}`] : []),
+    ].join(" ");
+  }
+  if (kind === "integration") {
+    return [
+      "[wave-integration]",
+      `state=${options.state}`,
+      `claims=${options.claims}`,
+      `conflicts=${options.conflicts}`,
+      `blockers=${options.blockers}`,
+      ...(options.detail ? [`detail=${options.detail}`] : []),
+    ].join(" ");
+  }
+  if (kind === "doc-closure") {
+    return [
+      "[wave-doc-closure]",
+      `state=${options.state}`,
+      ...(options.paths.length > 0 ? [`paths=${options.paths.join(",")}`] : []),
+      ...(options.detail ? [`detail=${options.detail}`] : []),
+    ].join(" ");
+  }
+  throw new Error(`Unknown signal kind: ${kind}`);
+}
+
+function assertCanonicalRoundTrip(kind, line) {
+  const candidate = parseStructuredSignalCandidate(line);
+  const parserKind = PARSER_KIND_BY_SIGNAL_KIND[kind] || kind;
+  if (!candidate?.accepted || candidate.kind !== parserKind || candidate.normalizedLine !== line) {
+    throw new Error(`wave signal ${kind} could not round-trip through the shipped structured-signal parser`);
+  }
+}
+
+function validate(kind, options) {
+  if (kind === "proof") {
+    if (!options.completion || !options.durability || !options.proof || !options.state) {
+      throw new Error("wave signal proof requires --completion, --durability, --proof, and --state");
+    }
+    options.completion = validateAllowedValue("--completion", options.completion, EXIT_CONTRACT_COMPLETION_VALUES);
+    options.durability = validateAllowedValue("--durability", options.durability, EXIT_CONTRACT_DURABILITY_VALUES);
+    options.proof = validateAllowedValue("--proof", options.proof, EXIT_CONTRACT_PROOF_VALUES);
+    options.state = validateAllowedValue("--state", options.state, PROOF_STATES);
+    options.detail = validateSafeField("--detail", options.detail);
+    return;
+  }
+  if (kind === "doc-delta" || kind === "doc-closure") {
+    if (!options.state) {
+      throw new Error(`wave signal ${kind} requires --state`);
+    }
+    options.state = validateAllowedValue(
+      "--state",
+      options.state,
+      kind === "doc-delta" ? EXIT_CONTRACT_DOC_IMPACT_VALUES : DOC_CLOSURE_STATES,
+    );
+    options.paths = validatePathList(options.paths);
+    options.detail = validateSafeField("--detail", options.detail);
+    return;
+  }
+  if (kind === "component") {
+    if (!options.componentId || !options.level || !options.state) {
+      throw new Error("wave signal component requires --id, --level, and --state");
+    }
+    options.componentId = validateSafeField("--id", options.componentId, { allowCommas: false });
+    options.level = validateSafeField("--level", options.level, { allowCommas: false }).toLowerCase();
+    options.state = validateAllowedValue("--state", options.state, PROOF_STATES);
+    options.detail = validateSafeField("--detail", options.detail);
+    if (!COMPONENT_ID_REGEX.test(options.componentId)) {
+      throw new Error("--id must use a canonical component token like runtime-render-snapshot");
+    }
+    if (!COMPONENT_LEVEL_REGEX.test(options.level)) {
+      throw new Error("--level must use a canonical component level token");
+    }
+    return;
+  }
+  if (kind === "integration") {
+    if (!options.state) {
+      throw new Error("wave signal integration requires --state");
+    }
+    options.state = validateAllowedValue("--state", options.state, INTEGRATION_STATES);
+    options.detail = validateSafeField("--detail", options.detail);
+    for (const field of ["claims", "conflicts", "blockers"]) {
+      const value = Number.parseInt(options[field], 10);
+      if (!Number.isFinite(value) || value < 0) {
+        throw new Error(`--${field} must be a non-negative integer`);
+      }
+      options[field] = String(value);
+    }
+    return;
+  }
+  throw new Error(`Unknown signal kind: ${kind}`);
+}
+
+export async function runSignalCli(argv) {
+  if (["--help", "-h", "help"].includes(String(argv[0] || "").trim().toLowerCase())) {
+    printUsage();
+    return;
+  }
+  const parsed = parseArgs(argv);
+  if (parsed.help || !parsed.kind) {
+    printUsage();
+    return;
+  }
+  validate(parsed.kind, parsed.options);
+  const line = buildLine(parsed.kind, parsed.options);
+  assertCanonicalRoundTrip(parsed.kind, line);
+  if (parsed.options.appendFile) {
+    ensureDirectory(path.dirname(parsed.options.appendFile));
+    fs.appendFileSync(parsed.options.appendFile, `${line}\n`, "utf8");
+  }
+  if (parsed.options.json) {
+    console.log(JSON.stringify({
+      kind: parsed.kind,
+      line,
+      appendFile: parsed.options.appendFile || null,
+    }, null, 2));
+    return;
+  }
+  console.log(line);
+}