/** @module
@summary Render expert guidance for a solver and handle failed consultations.

Expert agents return `ExpertGuidance`. Pass it through `renderGuidance` for
a coding agent's context and use its `checklist` as acceptance criteria.
`guidanceOrEmpty` turns a failed consultation into empty guidance.
*/

/** Guidance for a solver: domain conventions in `rules` and checkable
acceptance criteria in `checklist`. Empty lists mean the consult supplied
no domain-specific guidance. */
export type ExpertGuidance = {
  domain: string;
  rules: string[];
  checklist: string[]
}

export static const emptyGuidance: ExpertGuidance = {
  domain: "",
  rules: [],
  checklist: []
}

export def renderGuidance(guidance: ExpertGuidance): string {
  """Fold expert guidance into a context block the coding agent reads
  before it starts. Empty guidance yields an empty string."""
  if (guidance.rules.length == 0 && guidance.checklist.length == 0) {
    return ""
  }
  const rules = map(guidance.rules, \rule -> "- ${rule}").join("\n")
  const checks = map(guidance.checklist, \check -> "- ${check}").join("\n")
  return "Domain expertise for this task (${guidance.domain}):\n\nKey rules and conventions:\n${rules}\n\nAcceptance checklist — your finished work MUST satisfy every item:\n${checks}"
}

export def guidanceOrEmpty(result: Result<ExpertGuidance>): ExpertGuidance {
  """
  Return expert guidance, or empty guidance if the consultation failed.
  """
  return match(result) {
    success(guidance) => guidance
    failure(_) => emptyGuidance
  }
}