@1aboveio/skills 0.10.0

package/skills/engineering/resolve-issues/scripts/preflight-questions.mjs

@@ -0,0 +1,322 @@
+import { readFileSync } from 'node:fs'
+
+import {
+  defineCurrentTurnCapabilities,
+  defineQuestionAnswers,
+  defineQuestionSpec,
+  normalizeQuestionResponses,
+  planStructuredQuestions,
+} from '../../harness-runtime/index.mjs'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+
+const AUTONOMY_OPTIONS = Object.freeze([
+  Object.freeze({
+    id: 'autonomous',
+    label: 'Autonomous',
+    description: 'Pre-authorize reversible parks and delivery to the target branch.',
+  }),
+  Object.freeze({
+    id: 'supervised',
+    label: 'Supervised',
+    description: 'Stop for each decision that requires human authorization.',
+  }),
+])
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function nonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0
+}
+
+function invalid(message) {
+  throw new TypeError(`Invalid Resolve Issues pre-flight: ${message}`)
+}
+
+function defineOption(option, label) {
+  if (!isRecord(option)
+    || !nonEmptyString(option.id)
+    || !nonEmptyString(option.label)
+    || !nonEmptyString(option.description)) {
+    invalid(`${label} contains a malformed option`)
+  }
+  return Object.freeze({
+    id: option.id,
+    label: option.label,
+    description: option.description,
+    ...(nonEmptyString(option.family) ? { family: option.family } : {}),
+    ...(nonEmptyString(option.effort) ? { effort: option.effort } : {}),
+  })
+}
+
+function defineChoiceSet(value, label) {
+  if (!isRecord(value) || !Array.isArray(value.options) || !nonEmptyString(value.recommended)) {
+    invalid(`${label} choices require options and a recommended id`)
+  }
+  const ids = new Set()
+  const options = value.options.map((option) => {
+    if (isRecord(option) && ids.has(option.id)) invalid(`${label} choices contain a duplicate option`)
+    const defined = defineOption(option, `${label} choices`)
+    ids.add(defined.id)
+    return defined
+  })
+  if (!ids.has(value.recommended)) invalid(`${label} recommendation is not an option`)
+  return Object.freeze({ recommended: value.recommended, options: Object.freeze(options) })
+}
+
+// The reviewer slot is never asked (pre-flight.md step 2): it is FILLED from a
+// ranking the caller supplies -- the team default first, then the diversity
+// ladder -- and resolved against the answered implementer, because "reviewer !=
+// implementer" is the only thing that can collide and it is decidable without a
+// human. Accepts { default }, { candidates: [...] }, both, or the legacy asked
+// shape { recommended, options }, which ranks the recommendation first.
+function defineReviewRanking(value, label) {
+  if (!isRecord(value)) invalid(`${label} requires a default and/or ranked candidates`)
+  const teamDefault = value.default === undefined ? null : defineOption(value.default, `${label} default`)
+  const supplied = []
+  if (Array.isArray(value.candidates)) {
+    for (const candidate of value.candidates) supplied.push(defineOption(candidate, `${label} candidates`))
+  } else if (value.options !== undefined || value.recommended !== undefined) {
+    const choices = defineChoiceSet(value, label)
+    const recommended = choices.options.find((option) => option.id === choices.recommended)
+    supplied.push(recommended, ...choices.options.filter((option) => option.id !== choices.recommended))
+  }
+
+  const ranked = []
+  const ids = new Set()
+  for (const option of [...(teamDefault ? [teamDefault] : []), ...supplied]) {
+    if (ids.has(option.id)) continue
+    ids.add(option.id)
+    ranked.push(option)
+  }
+  if (ranked.length === 0) invalid(`${label} requires a default and/or ranked candidates`)
+  return Object.freeze({ default: teamDefault, candidates: Object.freeze(ranked) })
+}
+
+function question(id, header, prompt, choiceSet) {
+  return defineQuestionSpec({
+    id,
+    header,
+    prompt,
+    options: choiceSet.options.map(({ id: optionId, label, description }) => ({
+      id: optionId,
+      label,
+      description,
+    })),
+    recommendationOrder: [choiceSet.recommended],
+  })
+}
+
+function metadataEntries(choiceSet) {
+  return choiceSet.options.map((option) => [option.id, option])
+}
+
+export function planPreflightQuestions(value) {
+  if (!isRecord(value)) invalid('input must be an object')
+  const capabilities = defineCurrentTurnCapabilities(value.capabilities)
+  const implementation = defineChoiceSet(value.implementation, 'implementation')
+  const target = defineChoiceSet(value.target, 'target branch')
+  const review = defineReviewRanking(value.review, 'review')
+  const autonomy = Object.freeze({ recommended: 'autonomous', options: AUTONOMY_OPTIONS })
+
+  const questions = [
+    question('implementation', 'Implement', 'Which model should implement every unit in this run?', implementation),
+    question('target_branch', 'Target', 'Which fetched remote branch should every unit target?', target),
+    question('autonomy', 'Autonomy', 'How much reversible run activity should pre-flight authorize?', autonomy),
+  ]
+  const interaction = planStructuredQuestions(capabilities, questions)
+  const metadata = Object.freeze(Object.fromEntries([
+    ...metadataEntries(implementation),
+    ...review.candidates.map((option) => [option.id, option]),
+  ]))
+
+  return Object.freeze({
+    capabilities,
+    questions: Object.freeze(questions),
+    interaction,
+    // The top of the ranking, i.e. the fill unless the answered implementer
+    // collides with it; `record` resolves the final id and reports why.
+    defaulted: Object.freeze({ review: review.candidates[0].id }),
+    reviewRanking: Object.freeze(review.candidates.map((option) => option.id)),
+    freeTextQuestions: Object.freeze(interaction.kind === 'fallback'
+      ? questions.map(({ id, prompt }) => Object.freeze({ questionId: id, prompt }))
+      : []),
+    selections: Object.freeze({
+      implementation,
+      review,
+      target,
+      autonomy,
+    }),
+    modelMetadata: metadata,
+  })
+}
+
+function singleAnswer(answers, questionId) {
+  const values = answers[questionId]
+  if (!Array.isArray(values) || values.length !== 1 || !nonEmptyString(values[0])) {
+    invalid(`${questionId} requires exactly one answer`)
+  }
+  return values[0]
+}
+
+function selectedOption(choiceSet, id, { allowCustom = false } = {}) {
+  const option = choiceSet.options?.find((candidate) => candidate.id === id)
+  if (option) return option
+  if (allowCustom) return Object.freeze({ id, label: id, description: 'Human-named value.' })
+  invalid(`answer ${JSON.stringify(id)} is not available for its question`)
+}
+
+function modelPoint(models, slot, option) {
+  models[slot] = option.id
+  if (nonEmptyString(option.family)) models[`${slot}Family`] = option.family
+  if (nonEmptyString(option.effort) && option.effort !== 'high') models[`${slot}Effort`] = option.effort
+}
+
+// Resolve the reviewer fill now that the implementer is answered. Order: the
+// human's own override (they named it in the prompt), then the ranking's first
+// candidate that is not the implementer. Only a ranking with no distinct
+// candidate at all -- a single-model harness -- yields the implementer's own id,
+// and that is recorded as NOT INDEPENDENT rather than asked, because there is
+// nothing for a human to pick.
+function resolveReviewer(session, answers, implementation, customAllowed) {
+  const { default: teamDefault, candidates } = session.selections.review
+  if (Object.hasOwn(answers, 'review')) {
+    const named = singleAnswer(answers, 'review')
+    const option = selectedOption({ options: candidates }, named, { allowCustom: customAllowed })
+    return Object.freeze({ option, reason: 'human-named' })
+  }
+  const distinct = candidates.find((candidate) => candidate.id !== implementation.id)
+  if (!distinct) {
+    return Object.freeze({ option: candidates[0], reason: 'no-distinct-candidate' })
+  }
+  const reason = teamDefault && distinct.id === teamDefault.id ? 'team-default' : 'ladder'
+  return Object.freeze({ option: distinct, reason })
+}
+
+export function modelDiversity(implementation, review) {
+  if (implementation.id === review.id) {
+    return Object.freeze({
+      status: 'not-independent',
+      independent: false,
+      reason: 'identical-model-ids',
+    })
+  }
+  if (nonEmptyString(implementation.family)
+    && nonEmptyString(review.family)
+    && implementation.family === review.family) {
+    return Object.freeze({
+      status: 'reduced-diversity',
+      independent: true,
+      reason: 'same-family-different-model-ids',
+    })
+  }
+  return Object.freeze({ status: 'independent', independent: true, reason: null })
+}
+
+export function recordPreflightResponses(session, nativeResponses, options = {}) {
+  if (session?.interaction?.kind !== 'native') {
+    invalid('native responses require a native question plan')
+  }
+  const answers = normalizeQuestionResponses(session.interaction, nativeResponses)
+  return recordPreflightAnswers(session, answers, options)
+}
+
+export function recordPreflightAnswers(session, answerValue, { allowHumanNamed = false } = {}) {
+  if (!isRecord(session) || !isRecord(session.selections)) invalid('question session is malformed')
+  const answers = defineQuestionAnswers(answerValue)
+  if (Object.keys(answers).length === 0) {
+    return Object.freeze({ cancelled: true, manifestPatch: null, diversity: null, reviewFill: null })
+  }
+
+  const expectedIds = session.questions.map((item) => item.id)
+  // `review` is never a planned question, but a human who named the reviewer
+  // outright is honoured as an override rather than bounced.
+  const acceptedIds = [...expectedIds, 'review']
+  if (expectedIds.some((id) => !Object.hasOwn(answers, id))
+    || Object.keys(answers).some((id) => !acceptedIds.includes(id))) {
+    invalid('answers must complete exactly the planned question batch')
+  }
+
+  const customAllowed = allowHumanNamed || session.interaction.kind === 'fallback'
+  const implementationId = singleAnswer(answers, 'implementation')
+  let implementation = selectedOption(session.selections.implementation, implementationId, {
+    allowCustom: customAllowed,
+  })
+  implementation = session.modelMetadata[implementation.id] ?? implementation
+
+  const reviewFill = resolveReviewer(session, answers, implementation, customAllowed)
+  const review = session.modelMetadata[reviewFill.option.id] ?? reviewFill.option
+
+  const targetId = singleAnswer(answers, 'target_branch')
+  selectedOption(session.selections.target, targetId, { allowCustom: customAllowed })
+  const autonomy = singleAnswer(answers, 'autonomy')
+  selectedOption(session.selections.autonomy, autonomy)
+
+  const models = {}
+  modelPoint(models, 'implementation', implementation)
+  modelPoint(models, 'review', review)
+  const diversity = modelDiversity(implementation, review)
+  return Object.freeze({
+    cancelled: false,
+    manifestPatch: Object.freeze({
+      currentTurnCapabilities: session.capabilities,
+      models: Object.freeze(models),
+      targetBranch: targetId,
+      autonomy,
+    }),
+    diversity,
+    reviewFill: Object.freeze({ id: review.id, reason: reviewFill.reason }),
+  })
+}
+
+const CLI_USAGE = `preflight-questions <plan|record|record-native>
+
+Reads one JSON object from stdin and writes JSON to stdout.
+  plan          pre-flight input -> neutral questions + planned native/fallback interaction
+  record        { preflight, answers, allowHumanNamed? } -> complete manifest patch
+  record-native { preflight, responses, allowHumanNamed? } -> normalized complete manifest patch
+
+Exit 0 = result emitted; 1 = invalid input/contract; 2 = usage error.`
+
+export function runCli(argv, {
+  input = () => readFileSync(0, 'utf8'),
+  output = (text) => process.stdout.write(text),
+  error = (text) => process.stderr.write(text),
+} = {}) {
+  const command = argv[0]
+  if (command === '--help' || command === '-h' || command === 'help') {
+    output(`${CLI_USAGE}\n`)
+    return 0
+  }
+  if (!['plan', 'record', 'record-native'].includes(command) || argv.length !== 1) {
+    error(`${CLI_USAGE}\n`)
+    return 2
+  }
+
+  try {
+    const value = JSON.parse(input())
+    const result = command === 'plan'
+      ? planPreflightQuestions(value)
+      : command === 'record'
+        ? recordPreflightAnswers(
+          planPreflightQuestions(value.preflight),
+          value.answers,
+          { allowHumanNamed: value.allowHumanNamed === true },
+        )
+        : recordPreflightResponses(
+          planPreflightQuestions(value.preflight),
+          value.responses,
+          { allowHumanNamed: value.allowHumanNamed === true },
+        )
+    output(`${JSON.stringify(result, null, 2)}\n`)
+    return 0
+  } catch (cause) {
+    error(`preflight-questions: ${cause.message}\n`)
+    return 1
+  }
+}
+
+if (isMainModule(import.meta.url)) {
+  process.exitCode = runCli(process.argv.slice(2))
+}