@design-ai/cli 4.55.0 → 4.57.0

package/cli/lib/site-bundle-handoff-runbook-maps.mjs

@@ -0,0 +1,238 @@
+// Stage/action key-map builders and stage predicates for the bundle-handoff operator runbook.
+
+export const byKey = (rows, getValue) => Object.fromEntries(
+  rows.map((row, index) => [row.key, getValue(row, index)]),
+);
+export const fieldByKey = (rows, field) => byKey(rows, (row) => row[field]);
+export const hasCommands = (stage) => stage.commandCount > 0;
+export const isManualStage = (stage) => !hasCommands(stage);
+export const isRequiredStage = (stage) => stage.required;
+export const isOptionalStage = (stage) => !stage.required;
+export const usesReadOnlyRunPolicy = (stage) => stage.runPolicy === "read-only";
+export const usesLocalOutputRunPolicy = (stage) => stage.runPolicy === "writes-local-file";
+export const hasOutputFile = (stage) => stage.outputFiles.length > 0;
+export const callsExternalSystem = (stage) => stage.externalCalls;
+export const mutatesTargetRepo = (stage) => stage.targetRepoMutation;
+
+export function buildStageIdentityMaps(stages) {
+  const stageFieldByKey = (field) => fieldByKey(stages, field);
+  const stageKeys = stages.map((stage) => stage.key);
+  const stageByKey = byKey(stages, (stage) => stage);
+  const stageLabelByKey = stageFieldByKey("label");
+  const stageSummaryByKey = stageFieldByKey("reason");
+  return {
+    stageKeys,
+    stageByKey,
+    stageLabelByKey,
+    stageSummaryByKey,
+  };
+}
+
+export function buildStageActionStatusMaps(stageActionRows) {
+  const actionFieldByKey = (field) => fieldByKey(stageActionRows, field);
+  const stageActionTypeByKey = actionFieldByKey("actionType");
+  const stageActionLabelByKey = actionFieldByKey("actionLabel");
+  const stageActionInstructionsByKey = actionFieldByKey("actionInstruction");
+  const stageActionButtonLabelsByKey = actionFieldByKey("actionButtonLabel");
+  const stageActionAffordanceByKey = actionFieldByKey("actionAffordance");
+  const stageActionEnabledByKey = actionFieldByKey("actionEnabled");
+  const stageActionStatusByKey = actionFieldByKey("actionStatus");
+  const stageActionStatusLabelsByKey = actionFieldByKey("actionStatusLabel");
+  const stageActionStatusToneByKey = actionFieldByKey("actionStatusTone");
+  const stageActionDisabledReasonCodeByKey = actionFieldByKey("actionDisabledReasonCode");
+  const stageActionDisabledReasonByKey = actionFieldByKey("actionDisabledReason");
+  return {
+    stageActionRows,
+    stageActionTypeByKey,
+    stageActionLabelByKey,
+    stageActionInstructionsByKey,
+    stageActionButtonLabelsByKey,
+    stageActionAffordanceByKey,
+    stageActionEnabledByKey,
+    stageActionStatusByKey,
+    stageActionStatusLabelsByKey,
+    stageActionStatusToneByKey,
+    stageActionDisabledReasonCodeByKey,
+    stageActionDisabledReasonByKey,
+  };
+}
+
+export function buildStageActionDependencyMaps(stageActionRows) {
+  const actionFieldByKey = (field) => fieldByKey(stageActionRows, field);
+  const stageActionPrerequisiteKeysByKey = actionFieldByKey("actionPrerequisiteKeys");
+  const stageActionPrerequisiteLabelsByKey = actionFieldByKey("actionPrerequisiteLabels");
+  const stageActionPrerequisiteCountByKey = actionFieldByKey("actionPrerequisiteCount");
+  const stageActionHasPrerequisitesByKey = actionFieldByKey("actionHasPrerequisites");
+  const stageActionDependencyReasonCodeByKey = actionFieldByKey("actionDependencyReasonCode");
+  const stageActionDependencyReasonByKey = actionFieldByKey("actionDependencyReason");
+  const stageActionBlockedStageKeysByKey = actionFieldByKey("actionBlockedStageKeys");
+  const stageActionBlockedStageLabelsByKey = actionFieldByKey("actionBlockedStageLabels");
+  const stageActionBlockedStageCountByKey = actionFieldByKey("actionBlockedStageCount");
+  const stageActionBlocksStagesByKey = actionFieldByKey("actionBlocksStages");
+  const stageActionCompletionCriteriaByKey = actionFieldByKey("actionCompletionCriteria");
+  const stageActionCompletionCriteriaCountByKey = actionFieldByKey("actionCompletionCriteriaCount");
+  const stageActionHasCompletionCriteriaByKey = actionFieldByKey("actionHasCompletionCriteria");
+  return {
+    stageActionPrerequisiteKeysByKey,
+    stageActionPrerequisiteLabelsByKey,
+    stageActionPrerequisiteCountByKey,
+    stageActionHasPrerequisitesByKey,
+    stageActionDependencyReasonCodeByKey,
+    stageActionDependencyReasonByKey,
+    stageActionBlockedStageKeysByKey,
+    stageActionBlockedStageLabelsByKey,
+    stageActionBlockedStageCountByKey,
+    stageActionBlocksStagesByKey,
+    stageActionCompletionCriteriaByKey,
+    stageActionCompletionCriteriaCountByKey,
+    stageActionHasCompletionCriteriaByKey,
+  };
+}
+
+export function buildStageActionEvidenceMaps(stageActionRows) {
+  const actionFieldByKey = (field) => fieldByKey(stageActionRows, field);
+  const stageActionEvidenceRequirementsByKey = actionFieldByKey("actionEvidenceRequirements");
+  const stageActionEvidenceRequirementCountByKey = actionFieldByKey("actionEvidenceRequirementCount");
+  const stageActionRequiresEvidenceByKey = actionFieldByKey("actionRequiresEvidence");
+  const stageActionEvidenceTargetByKey = actionFieldByKey("actionEvidenceTarget");
+  const stageActionEvidenceTargetLabelByKey = actionFieldByKey("actionEvidenceTargetLabel");
+  return {
+    stageActionEvidenceRequirementsByKey,
+    stageActionEvidenceRequirementCountByKey,
+    stageActionRequiresEvidenceByKey,
+    stageActionEvidenceTargetByKey,
+    stageActionEvidenceTargetLabelByKey,
+  };
+}
+
+export function buildStageActionEvidenceCaptureMaps(stageActionRows) {
+  const actionFieldByKey = (field) => fieldByKey(stageActionRows, field);
+  const stageActionEvidenceCaptureFieldsByKey = actionFieldByKey("actionEvidenceCaptureFields");
+  const stageActionEvidenceCaptureFieldKeysByKey = actionFieldByKey("actionEvidenceCaptureFieldKeys");
+  const stageActionEvidenceCaptureFieldLabelsByKey = actionFieldByKey("actionEvidenceCaptureFieldLabels");
+  const stageActionEvidenceCaptureFieldPlaceholdersByKey = actionFieldByKey("actionEvidenceCaptureFieldPlaceholders");
+  const stageActionEvidenceCaptureFieldRequirementLabelsByKey = actionFieldByKey("actionEvidenceCaptureFieldRequirementLabels");
+  const stageActionEvidenceCaptureFieldAriaLabelsByKey = actionFieldByKey("actionEvidenceCaptureFieldAriaLabels");
+  const stageActionEvidenceCaptureFieldHelpTextsByKey = actionFieldByKey("actionEvidenceCaptureFieldHelpTexts");
+  const stageActionEvidenceCaptureFieldSectionKeysByKey = actionFieldByKey("actionEvidenceCaptureFieldSectionKeys");
+  const stageActionEvidenceCaptureFieldSectionLabelsByKey = actionFieldByKey("actionEvidenceCaptureFieldSectionLabels");
+  const stageActionEvidenceCaptureSectionKeysByKey = actionFieldByKey("actionEvidenceCaptureSectionKeys");
+  const stageActionEvidenceCaptureSectionLabelsByKey = actionFieldByKey("actionEvidenceCaptureSectionLabels");
+  const stageActionEvidenceCaptureSectionCountByKey = actionFieldByKey("actionEvidenceCaptureSectionCount");
+  const stageActionEvidenceCaptureFieldPayloadNamespacesByKey = actionFieldByKey("actionEvidenceCaptureFieldPayloadNamespaces");
+  const stageActionEvidenceCaptureFieldPayloadPathsByKey = actionFieldByKey("actionEvidenceCaptureFieldPayloadPaths");
+  const stageActionEvidenceCapturePayloadNamespacesByKey = actionFieldByKey("actionEvidenceCapturePayloadNamespaces");
+  const stageActionEvidenceCapturePayloadNamespaceCountByKey = actionFieldByKey("actionEvidenceCapturePayloadNamespaceCount");
+  const stageActionEvidenceCapturePayloadTemplateByKey = actionFieldByKey("actionEvidenceCapturePayloadTemplate");
+  const stageActionEvidenceCapturePayloadFlatTemplateByKey = actionFieldByKey("actionEvidenceCapturePayloadFlatTemplate");
+  const stageActionEvidenceCapturePayloadBindingsByKey = actionFieldByKey("actionEvidenceCapturePayloadBindings");
+  const stageActionEvidenceCaptureValidationSpecsByKey = actionFieldByKey("actionEvidenceCaptureValidationSpecs");
+  const stageActionEvidenceCaptureInitialValidationStatesByKey = actionFieldByKey("actionEvidenceCaptureInitialValidationStates");
+  const stageActionEvidenceCaptureInitialValidationDisplayMetadataByKey = actionFieldByKey("actionEvidenceCaptureInitialValidationDisplayMetadata");
+  const stageActionEvidenceCaptureInitialValidationChecklistByKey = actionFieldByKey("actionEvidenceCaptureInitialValidationChecklist");
+  const stageActionEvidenceCaptureInitialValidationChecklistSummaryByKey = actionFieldByKey("actionEvidenceCaptureInitialValidationChecklistSummary");
+  const stageActionEvidenceCaptureInitialValidationSummaryByKey = actionFieldByKey("actionEvidenceCaptureInitialValidationSummary");
+  const stageActionEvidenceCaptureFieldInputTypesByKey = actionFieldByKey("actionEvidenceCaptureFieldInputTypes");
+  const stageActionEvidenceCaptureFieldValueShapesByKey = actionFieldByKey("actionEvidenceCaptureFieldValueShapes");
+  const stageActionEvidenceCaptureFieldAcceptsMultipleByKey = actionFieldByKey("actionEvidenceCaptureFieldAcceptsMultiple");
+  const stageActionEvidenceCaptureFieldDefaultValuesByKey = actionFieldByKey("actionEvidenceCaptureFieldDefaultValues");
+  const stageActionEvidenceCaptureFieldEmptyValuesByKey = actionFieldByKey("actionEvidenceCaptureFieldEmptyValues");
+  const stageActionEvidenceCaptureFieldValidationRulesByKey = actionFieldByKey("actionEvidenceCaptureFieldValidationRules");
+  const stageActionEvidenceCaptureFieldMinLengthsByKey = actionFieldByKey("actionEvidenceCaptureFieldMinLengths");
+  const stageActionEvidenceCaptureFieldExamplesByKey = actionFieldByKey("actionEvidenceCaptureFieldExamples");
+  const stageActionEvidenceCaptureFieldValidationHintsByKey = actionFieldByKey("actionEvidenceCaptureFieldValidationHints");
+  const stageActionRequiredEvidenceCaptureFieldKeysByKey = actionFieldByKey("actionRequiredEvidenceCaptureFieldKeys");
+  const stageActionOptionalEvidenceCaptureFieldKeysByKey = actionFieldByKey("actionOptionalEvidenceCaptureFieldKeys");
+  const stageActionEvidenceCaptureFieldCountByKey = actionFieldByKey("actionEvidenceCaptureFieldCount");
+  const stageActionRequiredEvidenceCaptureFieldCountByKey = actionFieldByKey("actionRequiredEvidenceCaptureFieldCount");
+  const stageActionOptionalEvidenceCaptureFieldCountByKey = actionFieldByKey("actionOptionalEvidenceCaptureFieldCount");
+  const stageActionHasEvidenceCaptureFieldsByKey = actionFieldByKey("actionHasEvidenceCaptureFields");
+  return {
+    stageActionEvidenceCaptureFieldsByKey,
+    stageActionEvidenceCaptureFieldKeysByKey,
+    stageActionEvidenceCaptureFieldLabelsByKey,
+    stageActionEvidenceCaptureFieldPlaceholdersByKey,
+    stageActionEvidenceCaptureFieldRequirementLabelsByKey,
+    stageActionEvidenceCaptureFieldAriaLabelsByKey,
+    stageActionEvidenceCaptureFieldHelpTextsByKey,
+    stageActionEvidenceCaptureFieldSectionKeysByKey,
+    stageActionEvidenceCaptureFieldSectionLabelsByKey,
+    stageActionEvidenceCaptureSectionKeysByKey,
+    stageActionEvidenceCaptureSectionLabelsByKey,
+    stageActionEvidenceCaptureSectionCountByKey,
+    stageActionEvidenceCaptureFieldPayloadNamespacesByKey,
+    stageActionEvidenceCaptureFieldPayloadPathsByKey,
+    stageActionEvidenceCapturePayloadNamespacesByKey,
+    stageActionEvidenceCapturePayloadNamespaceCountByKey,
+    stageActionEvidenceCapturePayloadTemplateByKey,
+    stageActionEvidenceCapturePayloadFlatTemplateByKey,
+    stageActionEvidenceCapturePayloadBindingsByKey,
+    stageActionEvidenceCaptureValidationSpecsByKey,
+    stageActionEvidenceCaptureInitialValidationStatesByKey,
+    stageActionEvidenceCaptureInitialValidationDisplayMetadataByKey,
+    stageActionEvidenceCaptureInitialValidationChecklistByKey,
+    stageActionEvidenceCaptureInitialValidationChecklistSummaryByKey,
+    stageActionEvidenceCaptureInitialValidationSummaryByKey,
+    stageActionEvidenceCaptureFieldInputTypesByKey,
+    stageActionEvidenceCaptureFieldValueShapesByKey,
+    stageActionEvidenceCaptureFieldAcceptsMultipleByKey,
+    stageActionEvidenceCaptureFieldDefaultValuesByKey,
+    stageActionEvidenceCaptureFieldEmptyValuesByKey,
+    stageActionEvidenceCaptureFieldValidationRulesByKey,
+    stageActionEvidenceCaptureFieldMinLengthsByKey,
+    stageActionEvidenceCaptureFieldExamplesByKey,
+    stageActionEvidenceCaptureFieldValidationHintsByKey,
+    stageActionRequiredEvidenceCaptureFieldKeysByKey,
+    stageActionOptionalEvidenceCaptureFieldKeysByKey,
+    stageActionEvidenceCaptureFieldCountByKey,
+    stageActionRequiredEvidenceCaptureFieldCountByKey,
+    stageActionOptionalEvidenceCaptureFieldCountByKey,
+    stageActionHasEvidenceCaptureFieldsByKey,
+  };
+}
+
+export function buildStageExecutionMaps(stages) {
+  const stageFieldByKey = (field) => fieldByKey(stages, field);
+  const commandListByKey = (getValue) => byKey(stages, (stage) => stage.commands.map(getValue));
+  const stageKeysBy = (predicate) => stages.filter(predicate).map((stage) => stage.key);
+  const stageKindByKey = stageFieldByKey("kind");
+  const stageRequiredByKey = stageFieldByKey("required");
+  const stageRunPolicyByKey = stageFieldByKey("runPolicy");
+  const stageSafetyLevelByKey = stageFieldByKey("safetyLevel");
+  const stageCommandCountByKey = stageFieldByKey("commandCount");
+  const stageCommandKeysByKey = stageFieldByKey("commandKeys");
+  const stageCommandLabelsByKey = commandListByKey((command) => command.label);
+  const stageCommandStringsByKey = commandListByKey((command) => command.command);
+  const stageCommandArgsByKey = commandListByKey((command) => command.commandArgs);
+  const stageCommandRunPoliciesByKey = commandListByKey((command) => command.runPolicy);
+  const stageCommandSafetyLevelsByKey = commandListByKey((command) => command.safety?.safetyLevel || "");
+  const stageOutputFilesByKey = stageFieldByKey("outputFiles");
+  const stageHasCommandsByKey = byKey(stages, hasCommands);
+  const stageManualByKey = byKey(stages, isManualStage);
+  const stageWritesLocalFileByKey = stageFieldByKey("writesLocalFile");
+  const stageExternalCallsByKey = stageFieldByKey("externalCalls");
+  const stageTargetRepoMutationByKey = stageFieldByKey("targetRepoMutation");
+  const commandStageKeys = stageKeysBy(hasCommands);
+  const manualStageKeys = stageKeysBy(isManualStage);
+  return {
+    stageKindByKey,
+    stageRequiredByKey,
+    stageRunPolicyByKey,
+    stageSafetyLevelByKey,
+    stageCommandCountByKey,
+    stageCommandKeysByKey,
+    stageCommandLabelsByKey,
+    stageCommandStringsByKey,
+    stageCommandArgsByKey,
+    stageCommandRunPoliciesByKey,
+    stageCommandSafetyLevelsByKey,
+    stageOutputFilesByKey,
+    stageHasCommandsByKey,
+    stageManualByKey,
+    stageWritesLocalFileByKey,
+    stageExternalCallsByKey,
+    stageTargetRepoMutationByKey,
+    commandStageKeys,
+    manualStageKeys,
+  };
+}

package/cli/lib/site-bundle-handoff-runbook-next-step.mjs

@@ -0,0 +1,278 @@
+// Next-step stage/command/action summaries for the bundle-handoff operator runbook.
+
+export function buildNextStepState({
+  stageByKey,
+  commandByKey,
+  stageActionRows,
+  stageHumanLineByKey,
+  stageHumanLineDisplayRowByKey,
+}) {
+  const nextStageKey = "verifySourceBundle";
+  const nextCommandKey = "source.bundleCheck.strict";
+  const nextStage = stageByKey[nextStageKey] || null;
+  const nextStageActionRow = stageActionRows.find((stage) => stage.key === nextStageKey) || null;
+  const nextCommandEntry = commandByKey.get(nextCommandKey) || null;
+  const nextActionField = (field, fallback = "") => nextStageActionRow?.[field] || fallback;
+  const nextActionListField = (field) => nextActionField(field, []);
+  const nextActionObjectField = (field) => nextActionField(field, {});
+  const nextActionNumberField = (field) => nextActionField(field, 0);
+  const nextActionBooleanField = (field) => nextStageActionRow?.[field] === true;
+  const nextStageField = (field, fallback = "") => nextStage?.[field] || fallback;
+  const nextStageListField = (field) => nextStageField(field, []);
+  const nextStageBooleanField = (field) => nextStage?.[field] === true;
+  const nextStageCommandValues = (getValue) => nextStage?.commands?.map(getValue) || [];
+  const nextActionEvidenceProgressSummary = nextActionObjectField("actionEvidenceCaptureInitialValidationChecklistSummary");
+  const nextStageHumanLine = nextStage ? stageHumanLineByKey[nextStage.key] || "" : "";
+  const nextStageHumanLineDisplayRow = nextStage ? stageHumanLineDisplayRowByKey[nextStage.key] || {} : {};
+  const nextStageCommandCount = nextStageField("commandCount", 0);
+  const nextCommandField = (field, fallback = "") => nextCommandEntry?.[field] || fallback;
+  const nextCommandListField = (field) => nextCommandField(field, []);
+  const nextCommandSafety = nextCommandEntry?.safety || null;
+  const nextStageHumanLineSummary = nextStage ? {
+    stageKey: nextStage.key,
+    line: nextStageHumanLine,
+    hasEvidenceProgress: (nextActionEvidenceProgressSummary.itemCount || 0) > 0,
+    evidenceProgressStatus: nextActionEvidenceProgressSummary.status || "",
+    evidenceProgressLabel: nextActionEvidenceProgressSummary.progressLabel || "",
+    firstUncheckedEvidenceItemLabel: nextActionEvidenceProgressSummary.firstUncheckedItemLabel || "",
+  } : {};
+  const nextStageIdentity = {
+    nextStageLabel: nextStageField("label"),
+    nextStageSummary: nextStageField("reason"),
+    nextStageHumanLine,
+    nextStageHumanLineDisplayRow,
+    nextStageHumanLineSummary,
+  };
+  const nextStageActionStatus = {
+    nextStageActionType: nextActionField("actionType"),
+    nextStageActionLabel: nextActionField("actionLabel"),
+    nextStageActionInstruction: nextActionField("actionInstruction"),
+    nextStageActionButtonLabel: nextActionField("actionButtonLabel"),
+    nextStageActionAffordance: nextActionField("actionAffordance"),
+    nextStageActionEnabled: nextActionBooleanField("actionEnabled"),
+    nextStageActionStatus: nextActionField("actionStatus"),
+    nextStageActionStatusLabel: nextActionField("actionStatusLabel"),
+    nextStageActionStatusTone: nextActionField("actionStatusTone"),
+    nextStageActionDisabledReasonCode: nextActionField("actionDisabledReasonCode"),
+    nextStageActionDisabledReason: nextActionField("actionDisabledReason"),
+  };
+  const nextStageActionDependencies = {
+    nextStageActionPrerequisiteKeys: nextActionListField("actionPrerequisiteKeys"),
+    nextStageActionPrerequisiteLabels: nextActionListField("actionPrerequisiteLabels"),
+    nextStageActionPrerequisiteCount: nextActionNumberField("actionPrerequisiteCount"),
+    nextStageActionHasPrerequisites: nextActionBooleanField("actionHasPrerequisites"),
+    nextStageActionDependencyReasonCode: nextActionField("actionDependencyReasonCode"),
+    nextStageActionDependencyReason: nextActionField("actionDependencyReason"),
+    nextStageActionBlockedStageKeys: nextActionListField("actionBlockedStageKeys"),
+    nextStageActionBlockedStageLabels: nextActionListField("actionBlockedStageLabels"),
+    nextStageActionBlockedStageCount: nextActionNumberField("actionBlockedStageCount"),
+    nextStageActionBlocksStages: nextActionBooleanField("actionBlocksStages"),
+    nextStageActionCompletionCriteria: nextActionListField("actionCompletionCriteria"),
+    nextStageActionCompletionCriteriaCount: nextActionNumberField("actionCompletionCriteriaCount"),
+    nextStageActionHasCompletionCriteria: nextActionBooleanField("actionHasCompletionCriteria"),
+  };
+  const nextStageActionEvidence = {
+    nextStageActionEvidenceRequirements: nextActionListField("actionEvidenceRequirements"),
+    nextStageActionEvidenceRequirementCount: nextActionNumberField("actionEvidenceRequirementCount"),
+    nextStageActionRequiresEvidence: nextActionBooleanField("actionRequiresEvidence"),
+    nextStageActionEvidenceTarget: nextActionField("actionEvidenceTarget"),
+    nextStageActionEvidenceTargetLabel: nextActionField("actionEvidenceTargetLabel"),
+  };
+  const nextStageEvidenceCaptureFieldMetadata = {
+    nextStageActionEvidenceCaptureFields: nextActionListField("actionEvidenceCaptureFields"),
+    nextStageActionEvidenceCaptureFieldKeys: nextActionListField("actionEvidenceCaptureFieldKeys"),
+    nextStageActionEvidenceCaptureFieldLabels: nextActionListField("actionEvidenceCaptureFieldLabels"),
+    nextStageActionEvidenceCaptureFieldPlaceholders: nextActionListField("actionEvidenceCaptureFieldPlaceholders"),
+    nextStageActionEvidenceCaptureFieldRequirementLabels: nextActionListField("actionEvidenceCaptureFieldRequirementLabels"),
+    nextStageActionEvidenceCaptureFieldAriaLabels: nextActionListField("actionEvidenceCaptureFieldAriaLabels"),
+    nextStageActionEvidenceCaptureFieldHelpTexts: nextActionListField("actionEvidenceCaptureFieldHelpTexts"),
+    nextStageActionEvidenceCaptureFieldSectionKeys: nextActionListField("actionEvidenceCaptureFieldSectionKeys"),
+    nextStageActionEvidenceCaptureFieldSectionLabels: nextActionListField("actionEvidenceCaptureFieldSectionLabels"),
+    nextStageActionEvidenceCaptureSectionKeys: nextActionListField("actionEvidenceCaptureSectionKeys"),
+    nextStageActionEvidenceCaptureSectionLabels: nextActionListField("actionEvidenceCaptureSectionLabels"),
+    nextStageActionEvidenceCaptureSectionCount: nextActionNumberField("actionEvidenceCaptureSectionCount"),
+  };
+  const nextStageEvidenceCapturePayload = {
+    nextStageActionEvidenceCaptureFieldPayloadNamespaces: nextActionListField("actionEvidenceCaptureFieldPayloadNamespaces"),
+    nextStageActionEvidenceCaptureFieldPayloadPaths: nextActionListField("actionEvidenceCaptureFieldPayloadPaths"),
+    nextStageActionEvidenceCapturePayloadNamespaces: nextActionListField("actionEvidenceCapturePayloadNamespaces"),
+    nextStageActionEvidenceCapturePayloadNamespaceCount: nextActionNumberField("actionEvidenceCapturePayloadNamespaceCount"),
+    nextStageActionEvidenceCapturePayloadTemplate: nextActionObjectField("actionEvidenceCapturePayloadTemplate"),
+    nextStageActionEvidenceCapturePayloadFlatTemplate: nextActionObjectField("actionEvidenceCapturePayloadFlatTemplate"),
+    nextStageActionEvidenceCapturePayloadBindings: nextActionListField("actionEvidenceCapturePayloadBindings"),
+  };
+  const nextStageEvidenceCaptureValidation = {
+    nextStageActionEvidenceCaptureValidationSpecs: nextActionListField("actionEvidenceCaptureValidationSpecs"),
+    nextStageActionEvidenceCaptureInitialValidationStates: nextActionListField("actionEvidenceCaptureInitialValidationStates"),
+    nextStageActionEvidenceCaptureInitialValidationDisplayMetadata: nextActionListField("actionEvidenceCaptureInitialValidationDisplayMetadata"),
+    nextStageActionEvidenceCaptureInitialValidationChecklist: nextActionListField("actionEvidenceCaptureInitialValidationChecklist"),
+    nextStageActionEvidenceCaptureInitialValidationChecklistSummary: nextActionObjectField("actionEvidenceCaptureInitialValidationChecklistSummary"),
+    nextStageActionEvidenceCaptureInitialValidationSummary: nextActionObjectField("actionEvidenceCaptureInitialValidationSummary"),
+  };
+  const nextStageEvidenceCaptureFieldRules = {
+    nextStageActionEvidenceCaptureFieldInputTypes: nextActionListField("actionEvidenceCaptureFieldInputTypes"),
+    nextStageActionEvidenceCaptureFieldValueShapes: nextActionListField("actionEvidenceCaptureFieldValueShapes"),
+    nextStageActionEvidenceCaptureFieldAcceptsMultiple: nextActionListField("actionEvidenceCaptureFieldAcceptsMultiple"),
+    nextStageActionEvidenceCaptureFieldDefaultValues: nextActionListField("actionEvidenceCaptureFieldDefaultValues"),
+    nextStageActionEvidenceCaptureFieldEmptyValues: nextActionListField("actionEvidenceCaptureFieldEmptyValues"),
+    nextStageActionEvidenceCaptureFieldValidationRules: nextActionListField("actionEvidenceCaptureFieldValidationRules"),
+    nextStageActionEvidenceCaptureFieldMinLengths: nextActionListField("actionEvidenceCaptureFieldMinLengths"),
+    nextStageActionEvidenceCaptureFieldExamples: nextActionListField("actionEvidenceCaptureFieldExamples"),
+    nextStageActionEvidenceCaptureFieldValidationHints: nextActionListField("actionEvidenceCaptureFieldValidationHints"),
+    nextStageActionRequiredEvidenceCaptureFieldKeys: nextActionListField("actionRequiredEvidenceCaptureFieldKeys"),
+    nextStageActionOptionalEvidenceCaptureFieldKeys: nextActionListField("actionOptionalEvidenceCaptureFieldKeys"),
+  };
+  const nextStageEvidenceCaptureFieldCounts = {
+    nextStageActionEvidenceCaptureFieldCount: nextActionNumberField("actionEvidenceCaptureFieldCount"),
+    nextStageActionRequiredEvidenceCaptureFieldCount: nextActionNumberField("actionRequiredEvidenceCaptureFieldCount"),
+    nextStageActionOptionalEvidenceCaptureFieldCount: nextActionNumberField("actionOptionalEvidenceCaptureFieldCount"),
+    nextStageActionHasEvidenceCaptureFields: nextActionBooleanField("actionHasEvidenceCaptureFields"),
+  };
+  const nextStageEvidenceCapture = {
+    ...nextStageEvidenceCaptureFieldMetadata,
+    ...nextStageEvidenceCapturePayload,
+    ...nextStageEvidenceCaptureValidation,
+    ...nextStageEvidenceCaptureFieldRules,
+    ...nextStageEvidenceCaptureFieldCounts,
+  };
+  const nextStageClassification = {
+    nextStageKind: nextStageField("kind"),
+    nextStageRequired: nextStage?.required === true,
+    nextStageRunPolicy: nextStageField("runPolicy"),
+    nextStageSafetyLevel: nextStageField("safetyLevel"),
+  };
+  const nextStageCommandMetadata = {
+    nextStageCommandCount,
+    nextStageCommandLabels: nextStageCommandValues((command) => command.label),
+    nextStageCommands: nextStageCommandValues((command) => command.command),
+    nextStageCommandArgsList: nextStageCommandValues((command) => command.commandArgs),
+    nextStageCommandRunPolicies: nextStageCommandValues((command) => command.runPolicy),
+    nextStageCommandSafetyLevels: nextStageCommandValues((command) => command.safety?.safetyLevel || ""),
+  };
+  const nextStageExecutionContext = {
+    nextStageOutputFiles: nextStageListField("outputFiles"),
+    nextStageHasCommands: nextStageCommandCount > 0,
+    nextStageManual: nextStageCommandCount === 0,
+    nextStageWritesLocalFile: nextStageBooleanField("writesLocalFile"),
+    nextStageExternalCalls: nextStageBooleanField("externalCalls"),
+    nextStageTargetRepoMutation: nextStageBooleanField("targetRepoMutation"),
+    nextStageCommandKeys: nextStageListField("commandKeys"),
+  };
+  const nextStageCommandSummary = {
+    ...nextStageClassification,
+    ...nextStageCommandMetadata,
+    ...nextStageExecutionContext,
+  };
+  const nextCommandSummary = {
+    nextCommand: nextCommandField("command"),
+    nextCommandArgs: nextCommandListField("commandArgs"),
+    nextCommandRunPolicy: nextCommandField("runPolicy"),
+    nextCommandSafetyLevel: nextCommandSafety?.safetyLevel || "",
+    nextCommandSafety,
+    nextCommandEntry,
+  };
+  const nextActionCoreSummary = {
+    nextActionKey: nextStageKey,
+    nextActionType: nextActionField("actionType"),
+    nextActionLabel: nextActionField("actionLabel"),
+    nextActionEnabled: nextActionBooleanField("actionEnabled"),
+    nextActionStatus: nextActionField("actionStatus"),
+    nextActionStatusLabel: nextActionField("actionStatusLabel"),
+    nextActionStatusTone: nextActionField("actionStatusTone"),
+    nextActionDisabledReasonCode: nextActionField("actionDisabledReasonCode"),
+    nextActionPrerequisiteKeys: nextActionListField("actionPrerequisiteKeys"),
+    nextActionPrerequisiteLabels: nextActionListField("actionPrerequisiteLabels"),
+    nextActionPrerequisiteCount: nextActionNumberField("actionPrerequisiteCount"),
+    nextActionHasPrerequisites: nextActionBooleanField("actionHasPrerequisites"),
+    nextActionDependencyReasonCode: nextActionField("actionDependencyReasonCode"),
+    nextActionDependencyReason: nextActionField("actionDependencyReason"),
+    nextActionBlockedStageKeys: nextActionListField("actionBlockedStageKeys"),
+    nextActionBlockedStageLabels: nextActionListField("actionBlockedStageLabels"),
+    nextActionBlockedStageCount: nextActionNumberField("actionBlockedStageCount"),
+    nextActionBlocksStages: nextActionBooleanField("actionBlocksStages"),
+    nextActionCompletionCriteria: nextActionListField("actionCompletionCriteria"),
+    nextActionCompletionCriteriaCount: nextActionNumberField("actionCompletionCriteriaCount"),
+    nextActionHasCompletionCriteria: nextActionBooleanField("actionHasCompletionCriteria"),
+    nextActionEvidenceRequirements: nextActionListField("actionEvidenceRequirements"),
+    nextActionEvidenceRequirementCount: nextActionNumberField("actionEvidenceRequirementCount"),
+    nextActionRequiresEvidence: nextActionBooleanField("actionRequiresEvidence"),
+    nextActionEvidenceTarget: nextActionField("actionEvidenceTarget"),
+    nextActionEvidenceTargetLabel: nextActionField("actionEvidenceTargetLabel"),
+  };
+  const nextActionEvidenceCaptureFieldMetadata = {
+    nextActionEvidenceCaptureFields: nextActionListField("actionEvidenceCaptureFields"),
+    nextActionEvidenceCaptureFieldKeys: nextActionListField("actionEvidenceCaptureFieldKeys"),
+    nextActionEvidenceCaptureFieldLabels: nextActionListField("actionEvidenceCaptureFieldLabels"),
+    nextActionEvidenceCaptureFieldPlaceholders: nextActionListField("actionEvidenceCaptureFieldPlaceholders"),
+    nextActionEvidenceCaptureFieldRequirementLabels: nextActionListField("actionEvidenceCaptureFieldRequirementLabels"),
+    nextActionEvidenceCaptureFieldAriaLabels: nextActionListField("actionEvidenceCaptureFieldAriaLabels"),
+    nextActionEvidenceCaptureFieldHelpTexts: nextActionListField("actionEvidenceCaptureFieldHelpTexts"),
+    nextActionEvidenceCaptureFieldSectionKeys: nextActionListField("actionEvidenceCaptureFieldSectionKeys"),
+    nextActionEvidenceCaptureFieldSectionLabels: nextActionListField("actionEvidenceCaptureFieldSectionLabels"),
+    nextActionEvidenceCaptureSectionKeys: nextActionListField("actionEvidenceCaptureSectionKeys"),
+    nextActionEvidenceCaptureSectionLabels: nextActionListField("actionEvidenceCaptureSectionLabels"),
+    nextActionEvidenceCaptureSectionCount: nextActionNumberField("actionEvidenceCaptureSectionCount"),
+  };
+  const nextActionEvidenceCapturePayload = {
+    nextActionEvidenceCaptureFieldPayloadNamespaces: nextActionListField("actionEvidenceCaptureFieldPayloadNamespaces"),
+    nextActionEvidenceCaptureFieldPayloadPaths: nextActionListField("actionEvidenceCaptureFieldPayloadPaths"),
+    nextActionEvidenceCapturePayloadNamespaces: nextActionListField("actionEvidenceCapturePayloadNamespaces"),
+    nextActionEvidenceCapturePayloadNamespaceCount: nextActionNumberField("actionEvidenceCapturePayloadNamespaceCount"),
+    nextActionEvidenceCapturePayloadTemplate: nextActionObjectField("actionEvidenceCapturePayloadTemplate"),
+    nextActionEvidenceCapturePayloadFlatTemplate: nextActionObjectField("actionEvidenceCapturePayloadFlatTemplate"),
+    nextActionEvidenceCapturePayloadBindings: nextActionListField("actionEvidenceCapturePayloadBindings"),
+  };
+  const nextActionEvidenceCaptureValidation = {
+    nextActionEvidenceCaptureValidationSpecs: nextActionListField("actionEvidenceCaptureValidationSpecs"),
+    nextActionEvidenceCaptureInitialValidationStates: nextActionListField("actionEvidenceCaptureInitialValidationStates"),
+    nextActionEvidenceCaptureInitialValidationDisplayMetadata: nextActionListField("actionEvidenceCaptureInitialValidationDisplayMetadata"),
+    nextActionEvidenceCaptureInitialValidationChecklist: nextActionListField("actionEvidenceCaptureInitialValidationChecklist"),
+    nextActionEvidenceCaptureInitialValidationChecklistSummary: nextActionObjectField("actionEvidenceCaptureInitialValidationChecklistSummary"),
+    nextActionEvidenceCaptureInitialValidationSummary: nextActionObjectField("actionEvidenceCaptureInitialValidationSummary"),
+  };
+  const nextActionEvidenceCaptureFieldRules = {
+    nextActionEvidenceCaptureFieldInputTypes: nextActionListField("actionEvidenceCaptureFieldInputTypes"),
+    nextActionEvidenceCaptureFieldValueShapes: nextActionListField("actionEvidenceCaptureFieldValueShapes"),
+    nextActionEvidenceCaptureFieldAcceptsMultiple: nextActionListField("actionEvidenceCaptureFieldAcceptsMultiple"),
+    nextActionEvidenceCaptureFieldDefaultValues: nextActionListField("actionEvidenceCaptureFieldDefaultValues"),
+    nextActionEvidenceCaptureFieldEmptyValues: nextActionListField("actionEvidenceCaptureFieldEmptyValues"),
+    nextActionEvidenceCaptureFieldValidationRules: nextActionListField("actionEvidenceCaptureFieldValidationRules"),
+    nextActionEvidenceCaptureFieldMinLengths: nextActionListField("actionEvidenceCaptureFieldMinLengths"),
+    nextActionEvidenceCaptureFieldExamples: nextActionListField("actionEvidenceCaptureFieldExamples"),
+    nextActionEvidenceCaptureFieldValidationHints: nextActionListField("actionEvidenceCaptureFieldValidationHints"),
+    nextActionRequiredEvidenceCaptureFieldKeys: nextActionListField("actionRequiredEvidenceCaptureFieldKeys"),
+    nextActionOptionalEvidenceCaptureFieldKeys: nextActionListField("actionOptionalEvidenceCaptureFieldKeys"),
+  };
+  const nextActionEvidenceCaptureFieldCounts = {
+    nextActionEvidenceCaptureFieldCount: nextActionNumberField("actionEvidenceCaptureFieldCount"),
+    nextActionRequiredEvidenceCaptureFieldCount: nextActionNumberField("actionRequiredEvidenceCaptureFieldCount"),
+    nextActionOptionalEvidenceCaptureFieldCount: nextActionNumberField("actionOptionalEvidenceCaptureFieldCount"),
+    nextActionHasEvidenceCaptureFields: nextActionBooleanField("actionHasEvidenceCaptureFields"),
+  };
+  const nextActionRunContext = {
+    nextActionRunPolicy: nextStageField("runPolicy"),
+    nextActionSafetyLevel: nextStageField("safetyLevel"),
+  };
+  const nextActionSummary = {
+    ...nextActionCoreSummary,
+    ...nextActionEvidenceCaptureFieldMetadata,
+    ...nextActionEvidenceCapturePayload,
+    ...nextActionEvidenceCaptureValidation,
+    ...nextActionEvidenceCaptureFieldRules,
+    ...nextActionEvidenceCaptureFieldCounts,
+    ...nextActionRunContext,
+  };
+  const nextStepSummary = {
+    nextStageKey,
+    nextStage,
+    ...nextStageIdentity,
+    ...nextStageActionStatus,
+    ...nextStageActionDependencies,
+    ...nextStageActionEvidence,
+    ...nextStageEvidenceCapture,
+    ...nextStageCommandSummary,
+    nextCommandKey,
+    ...nextCommandSummary,
+  };
+  return { nextActionSummary, nextStepSummary };
+}

package/cli/lib/site-bundle-handoff-runbook-stage-metadata.mjs

@@ -0,0 +1,84 @@
+// Stage dependency and requirement metadata for Website Improvement bundle handoff runbooks.
+
+export function getStageLabel(stages, stageKey) {
+  return stages.find((stage) => stage.key === stageKey)?.label || stageKey;
+}
+
+export function getStageActionPrerequisiteKeys(stage) {
+  return ({
+    verifySourceBundle: [],
+    refreshHandoffSnapshot: [],
+    writeEffectiveTaskPrompt: ["verifySourceBundle"],
+    executeInTargetRepo: ["verifySourceBundle", "writeEffectiveTaskPrompt"],
+    recordEvidence: ["executeInTargetRepo"],
+  }[stage.key] || []);
+}
+
+export function getStageActionPrerequisiteLabels(stage, stages) {
+  return getStageActionPrerequisiteKeys(stage).map((stageKey) => getStageLabel(stages, stageKey));
+}
+
+export function getStageActionBlockedStageKeys(stage, stages) {
+  return stages
+    .filter((candidate) => getStageActionPrerequisiteKeys(candidate).includes(stage.key))
+    .map((candidate) => candidate.key);
+}
+
+export function getStageActionDependencyReasonCode(stage) {
+  return getStageActionPrerequisiteKeys(stage).length > 0 ? "requires-prerequisite-actions" : "";
+}
+
+export function getStageActionDependencyReason(stage) {
+  return ({
+    writeEffectiveTaskPrompt: "Complete Verify source bundle integrity before writing the selected task prompt.",
+    executeInTargetRepo: "Complete Verify source bundle integrity and Write effective task handoff prompt before implementing in the target website repo.",
+    recordEvidence: "Complete Execute the task in the target website repo before recording implementation evidence.",
+  }[stage.key] || "");
+}
+
+export function getStageActionCompletionCriteria(stage) {
+  return ({
+    verifySourceBundle: [
+      "Strict bundle check status is pass.",
+      "Checksum and generated-file drift counts are zero.",
+    ],
+    refreshHandoffSnapshot: [
+      "Strict handoff JSON can be regenerated without target-repo mutation.",
+    ],
+    writeEffectiveTaskPrompt: [
+      "Selected task handoff prompt is written to the expected local Markdown output file.",
+      "Output command remains local-output-file only.",
+    ],
+    executeInTargetRepo: [
+      "Target website repo has scoped implementation changes for the selected task.",
+      "Target repo lint/typecheck/build or equivalent verification has been run.",
+    ],
+    recordEvidence: [
+      "Changed files, verification commands, viewport checks, accessibility checks, remaining risks, and bundle digest are recorded.",
+    ],
+  }[stage.key] || []);
+}
+
+export function getStageActionEvidenceRequirements(stage) {
+  return ({
+    verifySourceBundle: [
+      "Strict bundle-check command output or JSON status.",
+      "Bundle digest and zero drift counts.",
+    ],
+    refreshHandoffSnapshot: [
+      "Refreshed strict handoff JSON snapshot when a wrapper consumes the latest contract.",
+    ],
+    writeEffectiveTaskPrompt: [
+      "Generated prompt output file path.",
+      "Selected task id and output filename.",
+    ],
+    executeInTargetRepo: [
+      "Target repo changed file list.",
+      "Target repo verification command results.",
+      "Viewport and accessibility check notes for affected pages.",
+    ],
+    recordEvidence: [
+      "Final evidence record includes changed files, verification, viewport/accessibility checks, risks, and bundle digest.",
+    ],
+  }[stage.key] || []);
+}