@chllming/wave-orchestration 0.9.10 → 0.9.12

package/scripts/wave-orchestrator/closure-policy.mjs

@@ -0,0 +1,319 @@
+function normalizeBoolean(value, fallback = false) {
+  if (value === undefined || value === null || value === "") {
+    return fallback;
+  }
+  if (typeof value === "boolean") {
+    return value;
+  }
+  const normalized = String(value || "")
+    .trim()
+    .toLowerCase();
+  if (["true", "1", "yes", "on"].includes(normalized)) {
+    return true;
+  }
+  if (["false", "0", "no", "off"].includes(normalized)) {
+    return false;
+  }
+  return fallback;
+}
+
+function normalizeThreshold(value, fallback) {
+  if (value === null || value === undefined || value === "") {
+    return fallback;
+  }
+  const parsed = Number.parseInt(String(value), 10);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : fallback;
+}
+
+function contradictionList(value) {
+  if (!value) {
+    return [];
+  }
+  if (value instanceof Map) {
+    return Array.from(value.values());
+  }
+  if (Array.isArray(value)) {
+    return value;
+  }
+  if (typeof value === "object") {
+    return Object.values(value);
+  }
+  return [];
+}
+
+function openCoordinationRecords(records = []) {
+  return (Array.isArray(records) ? records : []).filter(
+    (record) =>
+      !["resolved", "closed", "cancelled", "superseded"].includes(
+        String(record?.status || "")
+          .trim()
+          .toLowerCase(),
+      ),
+  );
+}
+
+function closureSignalsFromDerivedState(derivedState = {}) {
+  const integrationSummary = derivedState?.integrationSummary || {};
+  const docsQueueItems = Array.isArray(derivedState?.docsQueue?.items)
+    ? derivedState.docsQueue.items
+    : [];
+  const coordinationState = derivedState?.coordinationState || {};
+  const clarificationBarrier = derivedState?.clarificationBarrier || { ok: true };
+  const helperAssignmentBarrier = derivedState?.helperAssignmentBarrier || { ok: true };
+  const dependencyBarrier = derivedState?.dependencyBarrier || { ok: true };
+  const securitySummary = derivedState?.securitySummary || null;
+  const corridorSummary =
+    derivedState?.corridorSummary || derivedState?.securitySummary?.corridor || null;
+  const blockingContradictions = contradictionList(derivedState?.contradictions).filter(
+    (entry) =>
+      ["blocking", "high"].includes(String(entry?.severity || "").trim().toLowerCase()) &&
+      ((Array.isArray(entry?.impactedGates) && entry.impactedGates.includes("integrationBarrier")) ||
+        !Array.isArray(entry?.impactedGates) ||
+        entry.impactedGates.length === 0) &&
+      !["resolved", "closed", "cleared"].includes(
+        String(entry?.status || "")
+          .trim()
+          .toLowerCase(),
+      ),
+  );
+  const openClarifications = openCoordinationRecords(coordinationState?.clarifications);
+  const openHuman = [
+    ...openCoordinationRecords(coordinationState?.humanEscalations),
+    ...openCoordinationRecords(coordinationState?.humanFeedback),
+  ];
+  const blockingAssignments = (Array.isArray(derivedState?.capabilityAssignments)
+    ? derivedState.capabilityAssignments
+    : []
+  ).filter((assignment) => assignment?.blocking !== false);
+  const openDependencies = [
+    ...((Array.isArray(derivedState?.dependencySnapshot?.openInbound)
+      ? derivedState.dependencySnapshot.openInbound
+      : []) || []),
+    ...((Array.isArray(derivedState?.dependencySnapshot?.openOutbound)
+      ? derivedState.dependencySnapshot.openOutbound
+      : []) || []),
+    ...((Array.isArray(derivedState?.dependencySnapshot?.unresolvedInboundAssignments)
+      ? derivedState.dependencySnapshot.unresolvedInboundAssignments
+      : []) || []),
+  ];
+  const sharedPlanItems = docsQueueItems.filter((item) => item?.kind === "shared-plan");
+  const componentMatrixItems = docsQueueItems.filter((item) => item?.kind === "component-matrix");
+  return {
+    integrationReady:
+      integrationSummary?.recommendation === "ready-for-doc-closure",
+    openClaims: Array.isArray(integrationSummary?.openClaims) ? integrationSummary.openClaims : [],
+    conflictingClaims: Array.isArray(integrationSummary?.conflictingClaims)
+      ? integrationSummary.conflictingClaims
+      : [],
+    unresolvedBlockers: Array.isArray(integrationSummary?.unresolvedBlockers)
+      ? integrationSummary.unresolvedBlockers
+      : [],
+    changedInterfaces: Array.isArray(integrationSummary?.changedInterfaces)
+      ? integrationSummary.changedInterfaces
+      : [],
+    crossComponentImpacts: Array.isArray(integrationSummary?.crossComponentImpacts)
+      ? integrationSummary.crossComponentImpacts
+      : [],
+    proofGaps: Array.isArray(integrationSummary?.proofGaps) ? integrationSummary.proofGaps : [],
+    docGaps: Array.isArray(integrationSummary?.docGaps) ? integrationSummary.docGaps : [],
+    deployRisks: Array.isArray(integrationSummary?.deployRisks)
+      ? integrationSummary.deployRisks
+      : [],
+    inboundDependencies: Array.isArray(integrationSummary?.inboundDependencies)
+      ? integrationSummary.inboundDependencies
+      : [],
+    outboundDependencies: Array.isArray(integrationSummary?.outboundDependencies)
+      ? integrationSummary.outboundDependencies
+      : [],
+    helperAssignments: Array.isArray(integrationSummary?.helperAssignments)
+      ? integrationSummary.helperAssignments
+      : [],
+    sharedPlanItems,
+    componentMatrixItems,
+    blockingContradictions,
+    openClarifications,
+    openHuman,
+    blockingAssignments,
+    openDependencies,
+    clarificationBarrier,
+    helperAssignmentBarrier,
+    dependencyBarrier,
+    securityState:
+      integrationSummary?.securityState || securitySummary?.overallState || "not-applicable",
+    corridorSummary,
+  };
+}
+
+export function resolveClosureMode(waveNumber, thresholds) {
+  if (!thresholds) {
+    return "strict";
+  }
+  const bootstrapStart = normalizeThreshold(thresholds.bootstrap, 0);
+  const standardStart = Math.max(
+    bootstrapStart,
+    normalizeThreshold(thresholds.standard, 4),
+  );
+  const strictStart = Math.max(
+    standardStart,
+    normalizeThreshold(thresholds.strict, 10),
+  );
+  if (waveNumber >= strictStart) {
+    return "strict";
+  }
+  if (waveNumber >= standardStart) {
+    return "standard";
+  }
+  return "bootstrap";
+}
+
+export function resolveClosurePolicyConfig(source = {}) {
+  const validation = source?.laneProfile?.validation || source?.validation || {};
+  const rawThresholds =
+    source?.closureModeThresholds || validation?.closureModeThresholds || null;
+  const rawAutoClosure = source?.autoClosure || validation?.autoClosure || {};
+  return {
+    closureModeThresholds: {
+      bootstrap: normalizeThreshold(rawThresholds?.bootstrap, 0),
+      standard: normalizeThreshold(rawThresholds?.standard, 4),
+      strict: normalizeThreshold(rawThresholds?.strict, 10),
+    },
+    autoClosure: {
+      allowInferredIntegration: normalizeBoolean(
+        rawAutoClosure?.allowInferredIntegration,
+        false,
+      ),
+      allowAutoDocNoChange: normalizeBoolean(
+        rawAutoClosure?.allowAutoDocNoChange,
+        false,
+      ),
+      allowAutoDocProjection: normalizeBoolean(
+        rawAutoClosure?.allowAutoDocProjection,
+        false,
+      ),
+      allowSkipContQaInBootstrap: normalizeBoolean(
+        rawAutoClosure?.allowSkipContQaInBootstrap,
+        false,
+      ),
+    },
+  };
+}
+
+export function classifyClosureComplexity(derivedState = {}) {
+  const signals = closureSignalsFromDerivedState(derivedState);
+  const hasStrictSignals =
+    signals.blockingContradictions.length > 0 ||
+    signals.openClarifications.length > 0 ||
+    signals.openHuman.length > 0 ||
+    signals.clarificationBarrier?.ok === false ||
+    signals.helperAssignmentBarrier?.ok === false ||
+    signals.dependencyBarrier?.ok === false ||
+    signals.securityState === "blocked" ||
+    signals.corridorSummary?.blocking === true ||
+    (signals.corridorSummary?.ok === false &&
+      signals.corridorSummary?.requiredAtClosure !== false);
+  if (hasStrictSignals) {
+    return "strict-full-closure";
+  }
+  const hasSemanticIntegrationSignals =
+    signals.openClaims.length > 0 ||
+    signals.conflictingClaims.length > 0 ||
+    signals.unresolvedBlockers.length > 0 ||
+    signals.changedInterfaces.length > 0 ||
+    signals.crossComponentImpacts.length > 0 ||
+    signals.proofGaps.length > 0 ||
+    signals.deployRisks.length > 0 ||
+    signals.helperAssignments.length > 0 ||
+    signals.inboundDependencies.length > 0 ||
+    signals.outboundDependencies.length > 0 ||
+    signals.blockingAssignments.length > 0 ||
+    signals.openDependencies.length > 0;
+  if (hasSemanticIntegrationSignals) {
+    return "semantic-integration";
+  }
+  if (signals.sharedPlanItems.length > 0) {
+    return "semantic-docs";
+  }
+  return "low-entropy";
+}
+
+export function evaluateInferredIntegrationClosure(derivedState = {}, source = {}) {
+  const policy = resolveClosurePolicyConfig(source);
+  if (!policy.autoClosure.allowInferredIntegration) {
+    return null;
+  }
+  const signals = closureSignalsFromDerivedState(derivedState);
+  if (!signals.integrationReady) {
+    return null;
+  }
+  const hasSemanticSignals =
+    signals.openClaims.length > 0 ||
+    signals.conflictingClaims.length > 0 ||
+    signals.unresolvedBlockers.length > 0 ||
+    signals.changedInterfaces.length > 0 ||
+    signals.crossComponentImpacts.length > 0 ||
+    signals.proofGaps.length > 0 ||
+    signals.deployRisks.length > 0 ||
+    signals.helperAssignments.length > 0 ||
+    signals.inboundDependencies.length > 0 ||
+    signals.outboundDependencies.length > 0 ||
+    signals.blockingContradictions.length > 0 ||
+    signals.openClarifications.length > 0 ||
+    signals.openHuman.length > 0 ||
+    signals.clarificationBarrier?.ok === false ||
+    signals.helperAssignmentBarrier?.ok === false ||
+    signals.dependencyBarrier?.ok === false ||
+    signals.blockingAssignments.length > 0 ||
+    signals.openDependencies.length > 0 ||
+    signals.securityState === "blocked" ||
+    signals.corridorSummary?.blocking === true ||
+    (signals.corridorSummary?.ok === false &&
+      signals.corridorSummary?.requiredAtClosure !== false);
+  if (hasSemanticSignals) {
+    return null;
+  }
+  return {
+    ok: true,
+    state: "inferred",
+    statusCode: "pass",
+    detail:
+      "Integration closure was inferred from derived state; no semantic integration contradictions or blockers remain.",
+  };
+}
+
+export function evaluateDocumentationAutoClosure(
+  derivedState = {},
+  source = {},
+  options = {},
+) {
+  const policy = resolveClosurePolicyConfig(source);
+  const signals = closureSignalsFromDerivedState(derivedState);
+  const componentMatrixGate = options.componentMatrixGate || { ok: true };
+  if (
+    policy.autoClosure.allowAutoDocNoChange &&
+    signals.sharedPlanItems.length === 0 &&
+    signals.componentMatrixItems.length === 0
+  ) {
+    return {
+      ok: true,
+      state: "no-change",
+      statusCode: "pass",
+      detail:
+        "Documentation closure was auto-satisfied because derived state shows no shared-plan or component-matrix delta.",
+    };
+  }
+  if (
+    policy.autoClosure.allowAutoDocProjection &&
+    signals.sharedPlanItems.length === 0 &&
+    signals.componentMatrixItems.length > 0 &&
+    componentMatrixGate.ok
+  ) {
+    return {
+      ok: true,
+      state: "auto-closed",
+      statusCode: "pass",
+      detail:
+        "Documentation closure was auto-satisfied because only mechanical component-matrix reconciliation remained and the canonical matrix is already current.",
+    };
+  }
+  return null;
+}

package/scripts/wave-orchestrator/config.mjs

@@ -536,6 +536,21 @@ function normalizeValidation(rawValidation = {}) {
       standard: rawValidation.gateModeThresholds?.standard ?? 4,
       strict: rawValidation.gateModeThresholds?.strict ?? 10,
     },
+    closureModeThresholds: {
+      bootstrap: rawValidation.closureModeThresholds?.bootstrap ?? 0,
+      standard: rawValidation.closureModeThresholds?.standard ?? 4,
+      strict: rawValidation.closureModeThresholds?.strict ?? 10,
+    },
+    autoClosure: {
+      allowInferredIntegration:
+        normalizeOptionalBoolean(rawValidation.autoClosure?.allowInferredIntegration, false),
+      allowAutoDocNoChange:
+        normalizeOptionalBoolean(rawValidation.autoClosure?.allowAutoDocNoChange, false),
+      allowAutoDocProjection:
+        normalizeOptionalBoolean(rawValidation.autoClosure?.allowAutoDocProjection, false),
+      allowSkipContQaInBootstrap:
+        normalizeOptionalBoolean(rawValidation.autoClosure?.allowSkipContQaInBootstrap, false),
+    },
     bootstrapPassConditions: {
       requireA0Verdict: rawValidation.bootstrapPassConditions?.requireA0Verdict ?? false,
       requireProofSignals: rawValidation.bootstrapPassConditions?.requireProofSignals ?? false,

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

@@ -3,7 +3,10 @@ import path from "node:path";
 import {
   materializeAgentExecutionSummaryForRun,
   materializeAgentExecutionSummaries,
+  readClarificationBarrier,
   readRunExecutionSummary,
+  readWaveAssignmentBarrier,
+  readWaveDependencyBarrier,
 } from "./gate-engine.mjs";
 import {
   isOpenCoordinationStatus,
@@ -51,6 +54,11 @@ import {
   readWaveCorridorContext,
   waveCorridorContextPath,
 } from "./corridor.mjs";
+import {
+  classifyClosureComplexity,
+  resolveClosureMode,
+  resolveClosurePolicyConfig,
+} from "./closure-policy.mjs";
 
 export function waveCoordinationLogPath(lanePaths, waveNumber) {
   return path.join(lanePaths.coordinationDir, `wave-${waveNumber}.jsonl`);
@@ -573,6 +581,11 @@ export function buildWaveIntegrationSummary({
     securitySummary,
   });
   if (explicitIntegration) {
+    // When the integration steward explicitly asserts ready-for-doc-closure,
+    // clear synthesized proof/doc gaps — the steward has signed off on them.
+    const stewardClearedGaps =
+      explicitIntegration.state === "ready-for-doc-closure" &&
+      (explicitIntegration.blockers || 0) === 0;
     return {
       wave: wave.wave,
       lane: lanePaths.lane,
@@ -595,8 +608,8 @@ export function buildWaveIntegrationSummary({
       ),
       changedInterfaces: evidence.changedInterfaces,
       crossComponentImpacts: evidence.crossComponentImpacts,
-      proofGaps: evidence.proofGaps,
-      docGaps: evidence.docGaps,
+      proofGaps: stewardClearedGaps ? [] : evidence.proofGaps,
+      docGaps: stewardClearedGaps ? [] : evidence.docGaps,
       deployRisks: evidence.deployRisks,
       securityState: evidence.securityState,
       securityFindings: evidence.securityFindings,
@@ -712,12 +725,13 @@ export function buildWaveDerivedState({
     componentPromotions: wave.componentPromotions,
     runtimeAssignments,
   });
+  const corridorSummary = readWaveCorridorContext(lanePaths, wave.wave);
   const securitySummary = buildWaveSecuritySummary({
     lanePaths,
     wave,
     attempt,
     summariesByAgentId,
-    corridorSummary: readWaveCorridorContext(lanePaths, wave.wave),
+    corridorSummary,
   });
   const integrationSummary = buildWaveIntegrationSummary({
     lanePaths,
@@ -732,6 +746,35 @@ export function buildWaveDerivedState({
     dependencySnapshot,
     securitySummary,
   });
+  const closurePolicy = resolveClosurePolicyConfig(lanePaths);
+  const closureMode = resolveClosureMode(wave.wave, closurePolicy.closureModeThresholds);
+  const clarificationBarrier = readClarificationBarrier({
+    coordinationState,
+  });
+  const helperAssignmentBarrier = readWaveAssignmentBarrier(
+    {
+      capabilityAssignments,
+    },
+    {
+      gateMode: closureMode,
+    },
+  );
+  const dependencyBarrier = readWaveDependencyBarrier({
+    dependencySnapshot,
+  });
+  const closureComplexity = classifyClosureComplexity({
+    contradictions: coordinationState?.contradictions || [],
+    coordinationState,
+    docsQueue,
+    capabilityAssignments,
+    dependencySnapshot,
+    securitySummary,
+    corridorSummary,
+    integrationSummary,
+    clarificationBarrier,
+    helperAssignmentBarrier,
+    dependencyBarrier,
+  });
   const ledger = deriveWaveLedger({
     lane: lanePaths.lane,
     wave,
@@ -797,12 +840,17 @@ export function buildWaveDerivedState({
     dependencySnapshotMarkdownPath: waveDependencySnapshotMarkdownPath(lanePaths, wave.wave),
     securitySummary,
     securitySummaryPath: waveSecurityPath(lanePaths, wave.wave),
-    corridorSummary: readWaveCorridorContext(lanePaths, wave.wave),
+    corridorSummary,
     corridorSummaryPath: waveCorridorContextPath(lanePaths, wave.wave),
     integrationSummary,
     integrationSummaryPath: waveIntegrationPath(lanePaths, wave.wave),
     integrationMarkdownPath: waveIntegrationMarkdownPath(lanePaths, wave.wave),
     securityMarkdownPath: waveSecurityMarkdownPath(lanePaths, wave.wave),
+    clarificationBarrier,
+    helperAssignmentBarrier,
+    dependencyBarrier,
+    closureMode,
+    closureComplexity,
     ledger,
     ledgerPath: waveLedgerPath(lanePaths, wave.wave),
     responseMetrics,

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

@@ -53,6 +53,10 @@ import {
   openClarificationLinkedRequests,
 } from "./coordination-store.mjs";
 import { contradictionsBlockingGate } from "./contradiction-entity.mjs";
+import {
+  evaluateDocumentationAutoClosure,
+  evaluateInferredIntegrationClosure,
+} from "./closure-policy.mjs";
 
 function contradictionList(value) {
   if (value instanceof Map) {
@@ -860,7 +864,21 @@ export function readWaveComponentMatrixGate(wave, agentRuns, options = {}) {
 
 export function readWaveDocumentationGate(wave, agentRuns, options = {}) {
   const mode = normalizeReadMode(options.mode || "live");
-  const documentationAgentId = wave.documentationAgentId || "A9";
+  const documentationAgentId =
+    options.documentationAgentId || wave.documentationAgentId || "A9";
+  const autoClosure = evaluateDocumentationAutoClosure(options.derivedState, options, {
+    componentMatrixGate: options.componentMatrixGate,
+  });
+  if (autoClosure?.ok) {
+    return {
+      ok: true,
+      agentId: null,
+      statusCode: autoClosure.statusCode,
+      detail: autoClosure.detail,
+      logPath: null,
+      docClosureState: autoClosure.state,
+    };
+  }
   const docRun =
     agentRuns.find((run) => run.agent.agentId === documentationAgentId) ?? null;
   if (!docRun) {
@@ -1003,6 +1021,17 @@ export function readWaveIntegrationGate(wave, agentRuns, options = {}) {
     (options.requireIntegrationStewardFromWave !== null &&
       options.requireIntegrationStewardFromWave !== undefined &&
       wave.wave >= options.requireIntegrationStewardFromWave);
+  const autoClosure = evaluateInferredIntegrationClosure(options.derivedState, options);
+  if (autoClosure?.ok) {
+    return {
+      ok: true,
+      agentId: null,
+      statusCode: autoClosure.statusCode,
+      detail: autoClosure.detail,
+      logPath: null,
+      integrationState: autoClosure.state,
+    };
+  }
   const integrationRun =
     agentRuns.find((run) => run.agent.agentId === integrationAgentId) ?? null;
   if (!integrationRun) {
@@ -1059,10 +1088,16 @@ export function readWaveIntegrationGate(wave, agentRuns, options = {}) {
 }
 
 export function readWaveIntegrationBarrier(wave, agentRuns, derivedState, options = {}) {
-  const markerGate = readWaveIntegrationGate(wave, agentRuns, options);
+  const markerGate = readWaveIntegrationGate(wave, agentRuns, {
+    ...options,
+    derivedState,
+  });
   if (!markerGate.ok) {
     return markerGate;
   }
+  if (!markerGate.agentId) {
+    return markerGate;
+  }
   const integrationSummary = derivedState?.integrationSummary || null;
   if (!integrationSummary) {
     return {
@@ -1240,6 +1275,7 @@ export function buildGateSnapshot({
       securityRolePromptPath: lanePaths?.securityRolePromptPath,
       requireIntegrationStewardFromWave: lanePaths?.requireIntegrationStewardFromWave,
       laneProfile: lanePaths?.laneProfile,
+      autoClosure: lanePaths?.autoClosure,
       benchmarkCatalogPath: lanePaths?.laneProfile?.paths?.benchmarkCatalogPath,
       componentMatrixPayload,
       componentMatrixJsonPath,
@@ -1446,6 +1482,19 @@ export function readWaveComponentMatrixGatePure(wave, agentResults, options = {}
 
 export function readWaveDocumentationGatePure(wave, agentResults, options = {}) {
   const documentationAgentId = options.documentationAgentId || wave.documentationAgentId || "A9";
+  const autoClosure = evaluateDocumentationAutoClosure(options.derivedState, options, {
+    componentMatrixGate: options.componentMatrixGate,
+  });
+  if (autoClosure?.ok) {
+    return {
+      ok: true,
+      agentId: null,
+      statusCode: autoClosure.statusCode,
+      detail: autoClosure.detail,
+      logPath: null,
+      docClosureState: autoClosure.state,
+    };
+  }
   if (!waveDeclaresAgent(wave, documentationAgentId)) {
     return { ok: true, agentId: null, statusCode: "pass",
       detail: "No documentation steward declared for this wave.", logPath: null };
@@ -1507,6 +1556,17 @@ export function readWaveIntegrationGatePure(wave, agentResults, options = {}) {
   const integrationAgentId = options.integrationAgentId || wave.integrationAgentId || "A8";
   const requireIntegration = options.requireIntegrationSteward === true ||
     (options.requireIntegrationStewardFromWave != null && wave.wave >= options.requireIntegrationStewardFromWave);
+  const autoClosure = evaluateInferredIntegrationClosure(options.derivedState, options);
+  if (autoClosure?.ok) {
+    return {
+      ok: true,
+      agentId: null,
+      statusCode: autoClosure.statusCode,
+      detail: autoClosure.detail,
+      logPath: null,
+      integrationState: autoClosure.state,
+    };
+  }
   if (!waveDeclaresAgent(wave, integrationAgentId)) {
     return {
       ok: !requireIntegration,
@@ -1557,6 +1617,9 @@ export function buildGateSnapshotPure({ wave, agentResults, derivedState, valida
   const integrationMarkerGate = readWaveIntegrationGatePure(wave, agentResults, {
     integrationAgentId: laneConfig.integrationAgentId,
     requireIntegrationStewardFromWave: laneConfig.requireIntegrationStewardFromWave,
+    derivedState,
+    laneProfile: laneConfig.laneProfile,
+    autoClosure: laneConfig.autoClosure,
   });
   const integrationBarrier = (() => {
     if (!integrationMarkerGate.ok) { return integrationMarkerGate; }
@@ -1585,12 +1648,17 @@ export function buildGateSnapshotPure({ wave, agentResults, derivedState, valida
     }
     return integrationMarkerGate;
   })();
-  const documentationGate = readWaveDocumentationGatePure(wave, agentResults, {
-    documentationAgentId: laneConfig.documentationAgentId });
   const componentMatrixGate = readWaveComponentMatrixGatePure(wave, agentResults, {
     laneProfile: laneConfig.laneProfile, documentationAgentId: laneConfig.documentationAgentId,
     componentMatrixPayload: laneConfig.componentMatrixPayload,
     componentMatrixJsonPath: laneConfig.componentMatrixJsonPath });
+  const documentationGate = readWaveDocumentationGatePure(wave, agentResults, {
+    documentationAgentId: laneConfig.documentationAgentId,
+    derivedState,
+    laneProfile: laneConfig.laneProfile,
+    autoClosure: laneConfig.autoClosure,
+    componentMatrixGate,
+  });
   const contEvalGate = readWaveContEvalGatePure(wave, agentResults, {
     contEvalAgentId: laneConfig.contEvalAgentId, mode: validationMode,
     evalTargets: wave.evalTargets, benchmarkCatalogPath: laneConfig.benchmarkCatalogPath });

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.7.md",
+  "docs/guides/recommendations-0.9.12.md",
   "docs/guides/sandboxed-environments.md",
   "docs/guides/signal-wrappers.md",
   "docs/guides/terminal-surfaces.md",

package/scripts/wave-orchestrator/launcher.mjs

@@ -265,9 +265,9 @@ Options:
   --dry-run              Parse waves and update manifest only
   --terminal-surface <mode>
                         Terminal surface: ${TERMINAL_SURFACES.join(" | ")} (default: ${terminalSurface})
-  --no-dashboard         Disable per-wave tmux dashboard session
-  --cleanup-sessions     Kill lane tmux sessions after each wave (default: on)
-  --keep-sessions        Keep lane tmux sessions after each wave
+  --no-dashboard         Disable the per-wave dashboard projection session
+  --cleanup-sessions     Clean up lane tmux dashboard/projection sessions after each wave (default: on)
+  --keep-sessions        Keep lane tmux dashboard/projection sessions after each wave
   --keep-terminals       Do not remove temporary terminal entries after each wave
   --orchestrator-id <id> Stable orchestrator identity for cross-lane coordination
   --orchestrator-board <path>
@@ -477,6 +477,15 @@ function parseArgs(argv) {
   return { help: false, lanePaths, options, config };
 }
 
+function maybePrintOptionalTmuxNote(options) {
+  if (options.dryRun || options.terminalSurface !== "tmux" || options.dashboard) {
+    return;
+  }
+  console.log(
+    "[terminal-surface] tmux is optional here: live agents still run as detached processes, and tmux only affects dashboard/projection attach when dashboards are enabled.",
+  );
+}
+
 // --- Local wrappers that bind engine calls to launcher scope ---
 
 async function runClosureSweepPhase({
@@ -1062,11 +1071,12 @@ export async function runLauncherCli(argv) {
       console.log(
         `[dry-run] prompts and executor overlays written: ${path.relative(REPO_ROOT, lanePaths.executorOverlaysDir)}`,
       );
-      console.log("Dry run enabled, skipping tmux and executor launch.");
+      console.log("Dry run enabled, skipping live execution and optional dashboard/projection launch.");
       return;
     }
 
     preflightWavesForExecutorAvailability(filteredWaves, lanePaths);
+    maybePrintOptionalTmuxNote(options);
     const terminalRegistryEnabled = terminalSurfaceUsesTerminalRegistry(
       options.terminalSurface,
     );

package/scripts/wave-orchestrator/planner.mjs

@@ -2944,9 +2944,10 @@ async function runProjectSetupFlow(options = {}) {
       ),
     );
 
-    prompt.describe("\nHow do you want to watch agent sessions?");
-    prompt.describe("  vscode — agent sessions appear as VS Code terminal tabs");
-    prompt.describe("  tmux   — agent sessions run in tmux panes (terminal-native)");
+    prompt.describe("\nHow do you want to follow live runs?");
+    prompt.describe("Live agent execution stays process-backed either way; this only changes the operator surface.");
+    prompt.describe("  vscode — VS Code gets temporary terminal entries for agent logs and dashboards");
+    prompt.describe("  tmux   — terminal-native dashboard and projection surface with no VS Code integration");
     const defaultTerminalSurface = normalizeTerminalSurface(
       await prompt.askChoice(
         "Default terminal surface",