tspl-cli 0.0.0-stage → 0.1.1

package/src/shared/workflow-progress.js

@@ -0,0 +1,67 @@
+'use strict'
+const { completionProblems } = require('./workflow')
+const STAGES = ['implementing', 'testing', 'reviewing', 'awaiting-delivery', 'creating-pr', 'awaiting-ci']
+const LABELS = { implementing: 'Implementation', testing: 'Tests', reviewing: 'Review', 'awaiting-delivery': 'Push confirmation', 'creating-pr': 'Pull request', 'awaiting-ci': 'CI' }
+const effectiveStage = workflow => {
+  const stage = workflow.stage === 'blocked' ? workflow.resumeStage || 'implementing' : workflow.stage
+  return stage === 'repairing' ? 'testing' : stage
+}
+const workflowProgress = (task, at = new Date()) => {
+  const wf = task.workflow
+  if (!wf) return null
+  const current = effectiveStage(wf), position = wf.stage === 'ready' ? STAGES.length : STAGES.indexOf(current)
+  const options = task.plan?.workflow?.options || {}
+  const steps = STAGES.map((stage, i) => {
+    const saved = wf.stageResults?.[stage] || {}
+    let status = i < position ? 'done' : i === position ? 'running' : 'pending'
+    let reason = status === 'done' ? `${LABELS[stage]} completed; workflow advanced.` : status === 'pending' ? `Waiting for ${LABELS[STAGES[i - 1]] || 'plan approval'} to complete.` : `${LABELS[stage]} is running.`
+    if (stage === 'reviewing' && options.review === false || ['awaiting-delivery', 'creating-pr', 'awaiting-ci'].includes(stage) && options.pullRequest === false) { status = 'skipped'; reason = 'Not required by this task’s approved workflow.' }
+    else if (i === position) {
+      if (wf.stage === 'blocked') { status = 'failed'; reason = wf.blocker?.message || wf.blocker?.reason || 'The runner stopped without a detailed error.' }
+      else if (stage === 'awaiting-delivery') { status = 'waiting'; reason = 'A person must confirm pushing the branch and opening the pull request.' }
+      else if (stage === 'awaiting-ci') { status = 'waiting'; reason = 'Waiting for required CI checks; rerun to poll their results.' }
+      else if (stage === 'reviewing' && wf.review?.verdict === 'passed') { status = 'waiting'; reason = 'Review passed; complete the outstanding acceptance checks before delivery.' }
+      else if (!wf.leaseExpiresAt || new Date(wf.leaseExpiresAt).getTime() <= new Date(at).getTime()) { status = 'interrupted'; reason = 'No active runner heartbeat. The process exited or its lease expired; resume this stage.' }
+      else if (wf.stage === 'repairing') reason = `Repairing failures (repair rounds used: ${wf.attempts || 0}). ${saved.reason || ''}`
+    }
+    if (status === 'pending' && saved.status === 'failed') { status = 'failed'; reason = saved.reason || `${LABELS[stage]} failed; waiting for the repair and recheck.` }
+    if (stage === 'testing' && status === 'done') reason = `${(wf.evidence || []).filter(item => item.status === 'passed').length} checks passed on the recorded commits.`
+    if (stage === 'testing' && status === 'done') {
+      const problems = completionProblems({ plan: task.plan, workflow: wf, upTo: 'review' }).filter(problem =>
+        problem !== 'There is no separate review result.' && !/^The (separate review|review head)/.test(problem) && !/^Acceptance criterion/.test(problem))
+      if (problems.length) { status = 'failed'; reason = problems.join(' ') }
+    }
+    if (stage === 'reviewing' && status === 'done' && (!wf.review || wf.review.verdict !== 'passed' || !(wf.heads || []).every(head => (wf.review.heads || []).some(item => item.name === head.name && item.headSha === head.headSha)))) {
+      status = 'failed'; reason = 'A passing separate review for the current commits is missing.'
+    }
+    if (stage === 'reviewing' && status === 'done' && wf.review) reason = `Separate review ${wf.review.verdict}${wf.review.engine ? ` (${wf.review.engine})` : ''}.`
+    if (status === 'running' && saved.reason && wf.stage !== 'repairing') reason = saved.reason
+    return { stage, label: LABELS[stage], status, reason, startedAt: saved.startedAt || null, finishedAt: saved.finishedAt || null, command: stage === 'awaiting-delivery' ? `tspl task run ${task.key} --stage awaiting-delivery --confirm-delivery` : `tspl task run ${task.key} --stage ${stage}` }
+  })
+  return { stage: current, steps, current: steps.find(step => step.stage === current) || null }
+}
+/** Retry real work only; forward jumps must satisfy the same evidence gates as normal progression. */
+const retryWorkflow = (workflow, stage, plan) => {
+  if (!STAGES.includes(stage)) throw new Error(`Unknown retry stage: ${stage}`)
+  const current = effectiveStage(workflow)
+  if (workflow.stage === 'ready') throw new Error('This task is already ready; start a new task for further changes')
+  if (stage === 'implementing' && current !== 'implementing') throw new Error('Implementation has already completed; amend the plan for further code changes')
+  if (STAGES.indexOf(stage) > STAGES.indexOf(current)) {
+    const manualImplementation = current === 'implementing' && stage === 'testing' && workflow.heads?.some(head => head.baseSha && head.baseSha !== head.headSha) && workflow.heads.every(head => head.clean)
+    if (!manualImplementation) throw new Error(`Complete ${current} before retrying ${stage}; prerequisites cannot be skipped`)
+  }
+  if (stage === 'reviewing') {
+    const problems = completionProblems({ plan, workflow: { ...workflow, review: null }, upTo: 'review' }).filter(problem => problem !== 'There is no separate review result.' && !/^Acceptance criterion/.test(problem))
+    if (problems.length) throw new Error(`Run checks before review: ${problems.join(' ')}`)
+  }
+  if (['awaiting-delivery', 'creating-pr', 'awaiting-ci'].includes(stage)) {
+    const problems = completionProblems({ plan, workflow, upTo: 'review' })
+    if (problems.length) throw new Error(`Complete the required checks before delivery: ${problems.join(' ')}`)
+  }
+  const next = { ...workflow, stage, blocker: null, resumeStage: null }
+  if (stage === 'testing') { next.evidence = []; next.review = null; next.manualVerifications = [] }
+  if (stage === 'reviewing') next.review = null
+  if (stage === 'creating-pr' && !workflow.deliveryAuthorization) throw new Error('Confirm delivery before retrying pull request creation')
+  return next
+}
+module.exports = { workflowProgress, retryWorkflow, RETRY_STAGES: STAGES }

package/src/shared/workflow.js

@@ -0,0 +1,381 @@
+'use strict'
+
+const Crypto = require('crypto')
+
+const SCHEMA_VERSION = 1
+
+const CHECK_CATEGORIES = ['unit', 'integration', 'e2e', 'lint', 'typecheck', 'build']
+
+const TEST_CATEGORIES = ['unit', 'integration', 'e2e']
+
+const CHECK_PARSERS = ['node-tap', 'jest-json', 'playwright-json', 'custom', 'exit-code']
+
+const CI_POLICIES = ['discover', 'explicit', 'none']
+
+const WORKFLOW_STAGES = [
+  'planning',
+  'awaiting-approval',
+  'implementing',
+  'testing',
+  'repairing',
+  'reviewing',
+  'awaiting-delivery',
+  'creating-pr',
+  'awaiting-ci',
+  'ready',
+  'blocked',
+]
+
+/** Where each stage may go next. A blocked workflow resumes only at the stage it was blocked in. */
+const STAGE_TRANSITIONS = {
+  planning: ['awaiting-approval', 'blocked'],
+  'awaiting-approval': ['implementing', 'blocked'],
+  implementing: ['testing', 'blocked'],
+  testing: ['reviewing', 'repairing', 'blocked'],
+  repairing: ['testing', 'blocked'],
+  reviewing: ['awaiting-delivery', 'repairing', 'ready', 'blocked'],
+  'awaiting-delivery': ['creating-pr', 'testing', 'blocked'],
+  'creating-pr': ['awaiting-ci', 'testing', 'blocked'],
+  'awaiting-ci': ['ready', 'creating-pr', 'testing', 'blocked'],
+  ready: [],
+  blocked: [],
+}
+
+const BLOCKER_REASONS = ['stopped', 'tests-failed', 'review-failed', 'repairs-exhausted', 'out-of-plan', 'lease-lost', 'provider', 'ci-failed', 'other']
+
+/** Steps a task can switch off when it is created. Approvals can only be switched off by an owner, admin or PM. */
+const TASK_OPTIONS = {
+  scope: true,
+  planApproval: true,
+  pmApproval: true,
+  review: true,
+  pullRequest: true,
+}
+
+const APPROVAL_OPTIONS = ['scope', 'planApproval', 'pmApproval']
+
+const taskOptions = value => Object.fromEntries(Object.entries(TASK_OPTIONS).map(([key, fallback]) => [key, value && typeof value[key] === 'boolean' ? value[key] : fallback]))
+
+const EVIDENCE_STATUS = ['passed', 'failed', 'skipped', 'missing', 'cancelled', 'timed-out', 'stale']
+
+const WORKFLOW_DEFAULTS = { maxRepairRounds: 2, engineTimeoutMs: 120000, checkTimeoutMs: 600000 }
+
+const canonical = value => {
+  if (Array.isArray(value)) return value.map(canonical)
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.keys(value)
+        .sort()
+        .filter(key => value[key] !== undefined)
+        .map(key => [key, canonical(value[key])]),
+    )
+  }
+  return value
+}
+
+const hashValue = value => Crypto.createHash('sha256').update(JSON.stringify(canonical(value))).digest('hex')
+
+const checkHash = check =>
+  hashValue({
+    repo: check.repo,
+    cwd: check.cwd,
+    category: check.category,
+    command: check.command,
+    parser: check.parser,
+    timeoutMs: check.timeoutMs,
+  })
+
+const isObject = value => Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+
+const text = value => typeof value === 'string' && value.trim() !== ''
+
+const relativeInside = value => {
+  if (!text(value) || value.includes('\0') || value.startsWith('/') || /^[a-z]:[\\/]/i.test(value) || value.startsWith('~')) return false
+  return !value.split(/[\\/]/).includes('..')
+}
+
+const validateRepo = (repo, index) => {
+  const at = `repos[${index}]`
+  if (!isObject(repo)) throw new Error(`${at} must be an object`)
+  ;['id', 'name'].forEach(field => {
+    if (!text(repo[field])) throw new Error(`${at}.${field} is required`)
+  })
+  if (!repo.fingerprint && !repo.remoteHash) throw new Error(`${at} needs a fingerprint or remoteHash`)
+  if (!relativeInside(repo.path)) throw new Error(`${at}.path must be relative to the workspace and stay inside it`)
+  const delivery = repo.delivery
+  if (!isObject(delivery)) throw new Error(`${at}.delivery is required`)
+  if (!text(delivery.provider)) throw new Error(`${at}.delivery.provider is required`)
+  if (!text(delivery.repository)) throw new Error(`${at}.delivery.repository is required`)
+  if (!CI_POLICIES.includes(delivery.ciPolicy)) throw new Error(`${at}.delivery.ciPolicy must be one of ${CI_POLICIES.join(', ')}`)
+  const required = delivery.requiredChecks === undefined ? [] : delivery.requiredChecks
+  if (!Array.isArray(required) || required.some(item => !isObject(item) || !text(item.name))) {
+    throw new Error(`${at}.delivery.requiredChecks must be a list of { name, appId? }`)
+  }
+  if (delivery.ciPolicy === 'explicit' && !required.length) throw new Error(`${at}: an explicit CI policy needs at least one required check`)
+  if (delivery.ciPolicy === 'none' && delivery.noCiConfirmed !== true) {
+    throw new Error(`${at}: a no-CI policy must be confirmed (noCiConfirmed: true) in the project file`)
+  }
+  return { ...repo, delivery: { ...delivery, requiredChecks: required } }
+}
+
+const validateCheck = (check, repoNames, at = 'check') => {
+  if (!isObject(check)) throw new Error(`${at} must be an object`)
+  if (!text(check.id)) throw new Error(`${at}.id is required`)
+  const label = `check ${check.id}`
+  if (!repoNames.includes(check.repo)) throw new Error(`${label}: repo "${check.repo}" is not one of the project repos`)
+  if (!relativeInside(check.cwd)) throw new Error(`${label}: cwd must be an explicit relative path inside the repo`)
+  if (!CHECK_CATEGORIES.includes(check.category)) throw new Error(`${label}: category must be one of ${CHECK_CATEGORIES.join(', ')}`)
+  if (!text(check.command)) throw new Error(`${label}: command is required`)
+  if (!Number.isInteger(check.timeoutMs) || check.timeoutMs <= 0) throw new Error(`${label}: timeoutMs must be a positive integer`)
+  if (typeof check.required !== 'boolean') throw new Error(`${label}: required must be true or false`)
+  if (!CHECK_PARSERS.includes(check.parser)) throw new Error(`${label}: parser must be one of ${CHECK_PARSERS.join(', ')}`)
+  const isTest = TEST_CATEGORIES.includes(check.category)
+  if (check.parser === 'exit-code' && isTest) {
+    throw new Error(`${label}: exit-code is only allowed for non-test checks; test checks need a result parser or an attested custom command`)
+  }
+  if (check.parser === 'custom' && isTest && check.attested !== true) {
+    throw new Error(`${label}: a custom test command must be attested (attested: true) because tspl cannot count its results`)
+  }
+  if (check.artifacts !== undefined && check.artifacts !== null && !relativeInside(check.artifacts)) {
+    throw new Error(`${label}: artifacts must be a folder inside the check's working directory`)
+  }
+  const criteria = check.criteria === undefined ? [] : check.criteria
+  if (!Array.isArray(criteria) || criteria.some(n => !Number.isInteger(n) || n < 1)) {
+    throw new Error(`${label}: criteria must be a list of done-when numbers`)
+  }
+  return { ...check, attested: check.attested === true, criteria }
+}
+
+const validateProjectConfig = value => {
+  if (!isObject(value)) throw new Error('Project config must be an object')
+  if (value.schemaVersion === undefined) throw new Error('Project config has no schemaVersion')
+  if (value.schemaVersion > SCHEMA_VERSION) {
+    throw new Error(`Project config schemaVersion ${value.schemaVersion} is newer than this tspl understands (${SCHEMA_VERSION}). Update tspl.`)
+  }
+  if (value.schemaVersion !== SCHEMA_VERSION) throw new Error(`Unsupported project config schemaVersion ${value.schemaVersion}`)
+  if (!text(value.organization)) throw new Error('Project config needs an organization')
+  if (!isObject(value.project) || !text(value.project.id) || !text(value.project.slug)) {
+    throw new Error('Project config needs project.id and project.slug')
+  }
+  if (!Array.isArray(value.repos) || !value.repos.length) throw new Error('Project config needs at least one repo')
+  const repos = value.repos.map(validateRepo)
+  ;['id', 'name', 'path'].forEach(field => {
+    const seen = new Set()
+    repos.forEach(repo => {
+      if (seen.has(repo[field])) throw new Error(`Duplicate repo ${field} "${repo[field]}"`)
+      seen.add(repo[field])
+    })
+  })
+  const names = repos.map(repo => repo.name)
+  const rawChecks = value.checks === undefined ? [] : value.checks
+  if (!Array.isArray(rawChecks)) throw new Error('checks must be a list')
+  const checks = rawChecks.map((check, i) => validateCheck(check, names, `checks[${i}]`))
+  const ids = new Set()
+  checks.forEach(check => {
+    if (ids.has(check.id)) throw new Error(`Duplicate check id "${check.id}"`)
+    ids.add(check.id)
+  })
+  const workflow = { ...WORKFLOW_DEFAULTS, ...(value.workflow || {}) }
+  ;['maxRepairRounds', 'engineTimeoutMs', 'checkTimeoutMs'].forEach(field => {
+    if (!Number.isInteger(workflow[field]) || workflow[field] < 0) throw new Error(`workflow.${field} must be a non-negative integer`)
+  })
+  const instructions = value.instructions === undefined ? [] : value.instructions
+  if (!Array.isArray(instructions) || instructions.some(file => !relativeInside(file))) {
+    throw new Error('instructions must be a list of relative paths inside the project')
+  }
+  if (value.home !== undefined && (!relativeInside(value.home) || /[\\/]/.test(value.home))) {
+    throw new Error('home must be the name of the repository (inside the workspace folder) that holds the .tspl files')
+  }
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    ...(value.home ? { home: value.home } : {}),
+    organization: value.organization,
+    project: { id: value.project.id, slug: value.project.slug },
+    repos,
+    checks,
+    workflow,
+    instructions,
+  }
+}
+
+/** Shape check for a plan's frozen snapshot; the API refuses a plan whose snapshot is incomplete. */
+const validateSnapshot = snapshot => {
+  if (!isObject(snapshot) || snapshot.version !== 1) throw new Error('The workflow snapshot must be an object with version 1')
+  if (!text(snapshot.configHash) || !text(snapshot.instructionsHash)) throw new Error('The workflow snapshot needs configHash and instructionsHash')
+  if (!Array.isArray(snapshot.repos) || !snapshot.repos.length) throw new Error('The workflow snapshot needs the project repos')
+  const repos = snapshot.repos.map(validateRepo)
+  const names = repos.map(repo => repo.name)
+  if (!Array.isArray(snapshot.checks)) throw new Error('The workflow snapshot needs a list of checks')
+  const checks = snapshot.checks.map((check, i) => validateCheck(check, names, `checks[${i}]`))
+  const ids = new Set()
+  checks.forEach(check => {
+    if (ids.has(check.id)) throw new Error(`Duplicate check id "${check.id}"`)
+    ids.add(check.id)
+  })
+  if (!checks.some(check => check.required && TEST_CATEGORIES.includes(check.category))) {
+    throw new Error('The project has no required test check; add one to .tspl/project.json before planning a tested pull request')
+  }
+  const acceptance = snapshot.acceptance === undefined ? 0 : snapshot.acceptance
+  const manualCriteria = snapshot.manualCriteria === undefined ? [] : snapshot.manualCriteria
+  if (!Number.isInteger(acceptance) || acceptance < 0) throw new Error('acceptance must be a count')
+  if (!Array.isArray(manualCriteria) || manualCriteria.some(n => !Number.isInteger(n) || n < 1 || n > acceptance)) {
+    throw new Error('manualCriteria must be done-when numbers within the acceptance count')
+  }
+  const options = taskOptions(snapshot.options)
+  const maxRepairRounds = snapshot.maxRepairRounds === undefined ? WORKFLOW_DEFAULTS.maxRepairRounds : snapshot.maxRepairRounds
+  if (!Number.isInteger(maxRepairRounds) || maxRepairRounds < 0) throw new Error('maxRepairRounds must be a non-negative integer')
+  return { ...snapshot, repos, checks, acceptance, manualCriteria, maxRepairRounds, options }
+}
+
+const isTestCheck = check => TEST_CATEGORIES.includes(check.category)
+
+const requirementMet = (requirement, observations, headSha) =>
+  observations.some(
+    observation =>
+      observation.name === requirement.name &&
+      (requirement.appId === undefined || requirement.appId === null || observation.appId === requirement.appId) &&
+      observation.headSha === headSha &&
+      observation.status === 'completed' &&
+      observation.conclusion === 'success',
+  )
+
+const sameHeads = (recorded, heads) =>
+  Array.isArray(recorded) &&
+  heads.every(head => recorded.some(item => item.name === head.name && item.headSha === head.headSha))
+
+const evidenceProblems = (snapshot, workflow, headOf) => {
+  const problems = []
+  const evidence = Array.isArray(workflow.evidence) ? workflow.evidence : []
+  snapshot.checks
+    .filter(check => check.required)
+    .forEach(check => {
+      const found = evidence.filter(item => item.checkId === check.id)
+      if (!found.length) {
+        problems.push(`Required check ${check.id} is missing: it has no executed result.`)
+        return
+      }
+      if (found.length > 1) {
+        problems.push(`Required check ${check.id} has duplicate results.`)
+        return
+      }
+      const [item] = found
+      const head = headOf(check.repo)
+      if (!head) problems.push(`Required check ${check.id}: no recorded head for repo ${check.repo}.`)
+      else if (item.headSha !== head.headSha) problems.push(`Check ${check.id} ran on head ${item.headSha}, not the current head ${head.headSha} of ${check.repo}.`)
+      if (item.configHash !== snapshot.configHash) problems.push(`Check ${check.id} ran under a different approved config.`)
+      if (item.commandHash !== checkHash(check)) problems.push(`Check ${check.id} ran a different command than the approved one.`)
+      if (item.executed !== true) problems.push(`Check ${check.id} was not executed.`)
+      if (item.status !== 'passed') problems.push(`Check ${check.id} did not pass (status ${item.status}).`)
+      if (isTestCheck(check) && check.parser !== 'custom' && !(item.testCount > 0)) {
+        problems.push(`Check ${check.id} ran zero tests; a test count above zero is required.`)
+      }
+    })
+  const known = new Set(snapshot.checks.map(check => check.id))
+  evidence.filter(item => !known.has(item.checkId)).forEach(item => problems.push(`Result for unknown check ${item.checkId}.`))
+  return problems
+}
+
+const criteriaProblems = (snapshot, workflow, heads) => {
+  const problems = []
+  const covered = new Set(snapshot.checks.filter(check => check.required).flatMap(check => check.criteria || []))
+  const manual = new Set(snapshot.manualCriteria || [])
+  const verifications = Array.isArray(workflow.manualVerifications) ? workflow.manualVerifications : []
+  for (let n = 1; n <= (snapshot.acceptance || 0); n++) {
+    if (covered.has(n)) continue
+    if (manual.has(n) && verifications.some(item => item.criterion === n && item.userId && sameHeads(item.heads, heads))) continue
+    problems.push(`Acceptance criterion ${n} has no passing check and no human verification on the tested commits.`)
+  }
+  return problems
+}
+
+const deliveryProblems = (snapshot, workflow, heads) => {
+  const problems = []
+  const prs = Array.isArray(workflow.prs) ? workflow.prs : []
+  heads
+    .filter(head => head.baseSha !== head.headSha)
+    .forEach(head => {
+      const repo = snapshot.repos.find(item => item.name === head.name)
+      const found = prs.filter(item => item.repo === head.name)
+      if (!found.length) {
+        problems.push(`There is no pull request for ${head.name}.`)
+        return
+      }
+      if (found.length > 1) {
+        problems.push(`There are several pull request records for ${head.name}.`)
+        return
+      }
+      const [pr] = found
+      if (pr.headSha !== head.headSha) problems.push(`The pull request head ${pr.headSha} for ${head.name} is not the tested head ${head.headSha}.`)
+      if (pr.draft) problems.push(`The pull request for ${head.name} is still a draft.`)
+      if (pr.state !== 'open') problems.push(`The pull request for ${head.name} is ${pr.state}, not open.`)
+      const delivery = repo && repo.delivery
+      if (delivery && delivery.ciPolicy === 'none' && delivery.noCiConfirmed === true) return
+      const required = Array.isArray(pr.requiredChecks) ? pr.requiredChecks : []
+      if (!required.length) {
+        problems.push(`The required CI checks for ${head.name} were not determined; an empty set is not success.`)
+        return
+      }
+      const configured = (delivery && delivery.requiredChecks) || []
+      configured
+        .filter(item => !required.some(r => r.name === item.name && (item.appId === undefined || r.appId === item.appId)))
+        .forEach(item => problems.push(`Configured required CI check ${item.name} is missing from the pull request for ${head.name}.`))
+      required
+        .filter(item => !requirementMet(item, pr.checks || [], head.headSha))
+        .forEach(item => problems.push(`Required CI check ${item.name} has not succeeded on ${head.headSha} for ${head.name}.`))
+    })
+  return problems
+}
+
+/** upTo: 'review' skips the pull request conditions (used before delivery starts). */
+const completionProblems = ({ plan, workflow, upTo = 'ready' }) => {
+  const snapshot = plan && plan.workflow
+  if (!isObject(snapshot) || !Array.isArray(snapshot.checks)) return ['The approved plan has no workflow snapshot.']
+  if (!isObject(workflow)) return ['The task has no workflow record.']
+  const problems = []
+  if (workflow.configHash !== snapshot.configHash) problems.push('The workflow config does not match the approved config hash.')
+  const heads = Array.isArray(workflow.heads) ? workflow.heads : []
+  if (!heads.length) {
+    problems.push('There are no recorded heads to test.')
+    return problems
+  }
+  heads.filter(head => head.clean !== true).forEach(head => problems.push(`${head.name} has uncommitted changes; checks must run on a clean committed branch.`))
+  const headOf = name => heads.find(head => head.name === name)
+  problems.push(...evidenceProblems(snapshot, workflow, headOf))
+  problems.push(...criteriaProblems(snapshot, workflow, heads))
+  const options = taskOptions(snapshot.options)
+  const review = workflow.review
+  if (!options.review) {
+    // the task was created without a separate review
+  } else if (!isObject(review)) problems.push('There is no separate review result.')
+  else {
+    if (review.verdict !== 'passed') problems.push('The separate review did not pass.')
+    heads.forEach(head => {
+      const seen = (review.heads || []).find(item => item.name === head.name)
+      if (!seen || seen.headSha !== head.headSha) problems.push(`The review head for ${head.name} (${seen ? seen.headSha : 'none'}) is not the tested head ${head.headSha}.`)
+    })
+  }
+  if (upTo === 'ready' && options.pullRequest) problems.push(...deliveryProblems(snapshot, workflow, heads))
+  return problems
+}
+
+module.exports = {
+  SCHEMA_VERSION,
+  CHECK_CATEGORIES,
+  TEST_CATEGORIES,
+  CHECK_PARSERS,
+  CI_POLICIES,
+  WORKFLOW_STAGES,
+  STAGE_TRANSITIONS,
+  TASK_OPTIONS,
+  APPROVAL_OPTIONS,
+  taskOptions,
+  BLOCKER_REASONS,
+  EVIDENCE_STATUS,
+  WORKFLOW_DEFAULTS,
+  hashValue,
+  checkHash,
+  validateProjectConfig,
+  validateCheck,
+  validateSnapshot,
+  completionProblems,
+}

package/src/stack-detector.js

@@ -0,0 +1,47 @@
+'use strict'
+
+const Fs = require('fs')
+const Path = require('path')
+
+const readPackage = dir => {
+  try {
+    return JSON.parse(Fs.readFileSync(Path.join(dir, 'package.json'), 'utf8'))
+  } catch (err) {
+    return null
+  }
+}
+
+const PYTHON_MARKERS = ['pyproject.toml', 'requirements.txt', 'setup.py', 'Pipfile']
+
+const isPython = dir =>
+  PYTHON_MARKERS.some(file => Fs.existsSync(Path.join(dir, file))) ||
+  Fs.readdirSync(dir).some(file => file.endsWith('.py'))
+
+const detectStacks = dir => {
+  const pkg = readPackage(dir)
+  if (!pkg) {
+    return isPython(dir) ? ['python'] : []
+  }
+
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies }
+  const has = name => Object.prototype.hasOwnProperty.call(deps, name)
+  const stacks = []
+
+  if (has('@hapi/hapi') || has('hapi')) {
+    stacks.push('node-hapi-api')
+  }
+  if (has('@angular/core')) {
+    stacks.push('angular-web')
+  }
+  if (has('react-native') || has('expo')) {
+    stacks.push('react-native')
+  } else if (has('react')) {
+    stacks.push('react-web')
+  }
+
+  return stacks.length ? stacks : ['node']
+}
+
+module.exports = {
+  detectStacks,
+}

package/src/task/approaches.js

@@ -0,0 +1,53 @@
+'use strict'
+const { request } = require('../api-client')
+const { bindApproach, approachBasis } = require('../shared')
+const taskUrl = (projectId, key) => `/api/v1/projects/${projectId}/tasks/${encodeURIComponent(key)}`
+const fetchApproaches = (projectId, key) => request('GET', taskUrl(projectId, key))
+const proposeApproaches = (projectId, key, proposal) => request('POST', `${taskUrl(projectId, key)}/approaches`, proposal)
+const selectApproach = (projectId, key, selection) => request('POST', `${taskUrl(projectId, key)}/approaches/selection`, selection)
+const renderApproaches = approaches => {
+  if (!approaches) return 'Read the relevant code, then call propose_approaches with two or three options and one recommendation.'
+  if (approaches.selection) {
+    const option = approaches.options.find(item => item.id === approaches.selection.optionId)
+    if (!option) throw new Error('Selected approach not found; refresh the task')
+    return [
+      `IMPLEMENTATION APPROACHES v${approaches.version}`,
+      `Selected: ${option.id} — ${option.title}${option.id === approaches.recommendedId ? ' (Recommended)' : ''}`,
+      option.summary, `Benefits: ${option.benefits.join('; ')}`, `Drawbacks: ${option.drawbacks.join('; ')}`,
+      ...(option.files.length ? [`Files: ${option.files.join(', ')}`] : []),
+      `Create the plan from this choice using approach {version: ${approaches.version}, optionId: "${option.id}"}. Existing plan approvals still apply.`,
+    ].join('\n')
+  }
+  const lines = [`IMPLEMENTATION APPROACHES v${approaches.version}`]
+  approaches.options.forEach((option, i) => lines.push(
+    `${i + 1}. ${option.title}${option.id === approaches.recommendedId ? ' (Recommended)' : ''} [${option.id}]`,
+    `   ${option.summary}`, `   Benefits: ${option.benefits.join('; ')}`, `   Drawbacks: ${option.drawbacks.join('; ')}`,
+    ...(option.files.length ? [`   Files: ${option.files.join(', ')}`] : []),
+  ))
+  lines.push(`Recommendation: ${approaches.reason}`)
+  lines.push('Show these options using your question tool, or a numbered chat list. Wait for an explicit user answer; never select automatically. Then call select_approach with the version and chosen option ID.')
+  return lines.join('\n')
+}
+/** Refresh, persist and ask before invoking the final planner. Dependencies keep terminal input injectable. */
+const chooseForPlanning = async (projectId, key, { generate, choose, fetch = fetchApproaches, propose = proposeApproaches, select = selectApproach, signal }) => {
+  signal?.throwIfAborted()
+  let task = await fetch(projectId, key)
+  signal?.throwIfAborted()
+  const approaches = task.approaches
+  if (!approaches || approaches.basis !== approachBasis(task.card)) {
+    const proposal = await generate(task)
+    signal?.throwIfAborted()
+    task = await propose(projectId, key, { ...proposal, expectedVersion: approaches ? approaches.version : 0 })
+    signal?.throwIfAborted()
+  }
+  if (!task.approaches.selection) {
+    if (!choose) return { waitingForSelection: true, task, note: `${renderApproaches(task.approaches)}\nChoose explicitly: tspl task choose ${key} <option-id> --version ${task.approaches.version}` }
+    const optionId = await choose(task.approaches)
+    signal?.throwIfAborted()
+    task = await select(projectId, key, { version: task.approaches.version, optionId, via: 'cli' })
+  }
+  signal?.throwIfAborted()
+  bindApproach(task.approaches, task.card, { version: task.approaches.version, optionId: task.approaches.selection.optionId })
+  return { task }
+}
+module.exports = { fetchApproaches, proposeApproaches, selectApproach, renderApproaches, chooseForPlanning }

package/src/task/branch-choice.js

@@ -0,0 +1,69 @@
+'use strict'
+
+const { execFileSync } = require('child_process')
+
+const FETCH_TIMEOUT = 60 * 1000
+
+const tryGit = (dir, args, timeout) => {
+  try {
+    return execFileSync('git', ['-C', dir, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout }).trim()
+  } catch (err) {
+    return null
+  }
+}
+
+const validBranch = name => tryGit('.', ['check-ref-format', '--branch', name]) !== null
+
+/** Local and origin branches of a repo, one entry per name, after a fetch so new remote branches show up. */
+const listBranches = dir => {
+  tryGit(dir, ['fetch', 'origin', '--prune'], FETCH_TIMEOUT)
+  const refs = (tryGit(dir, ['for-each-ref', '--format=%(refname)', 'refs/heads', 'refs/remotes/origin']) || '').split('\n').filter(Boolean)
+  const names = refs
+    .map(ref => ref.replace(/^refs\/heads\//, '').replace(/^refs\/remotes\/origin\//, ''))
+    .filter(name => name && name !== 'HEAD' && !name.startsWith('refs/'))
+  return [...new Set(names)].sort()
+}
+
+/** Picks the base branch from the repo's branches; typing filters the list. The suggested base comes first. */
+const pickBase = (repo, search) => {
+  const branches = listBranches(repo.path)
+  const ordered = [repo.base, repo.current, ...branches].filter((name, i, all) => name && branches.includes(name) && all.indexOf(name) === i)
+  const label = name => `${name}${name === repo.base ? '  (project base branch)' : ''}${name === repo.current ? '  (checked out now)' : ''}`
+  return search({
+    message: `${repo.name}: start from which branch? (type to filter)`,
+    pageSize: 12,
+    source: async term => {
+      const wanted = String(term || '').trim().toLowerCase()
+      const matches = ordered.filter(name => name.toLowerCase().includes(wanted)).map(name => ({ name: label(name), value: name }))
+      return matches.length ? matches : [{ name: `No branch matches "${term}"`, value: null, disabled: true }]
+    },
+  })
+}
+
+/**
+ * Asks, before any code is written, which branch each repo starts from and the name of the new branch.
+ * Returns { bases, branch }, or null when the person answers no at the end.
+ */
+const askBranchChoice = async (proposal, { input, confirm, search }) => {
+  console.log('\nBefore coding starts, choose the branches.')
+  const bases = {}
+  for (const repo of proposal.repos) {
+    bases[repo.name] = await pickBase(repo, search)
+  }
+  const branch = await input({
+    message: 'Name of the new branch to create for this task:',
+    default: proposal.branch,
+    validate: value => {
+      const name = value.trim()
+      if (!name) return 'Give a branch name'
+      if (!validBranch(name)) return `"${name}" is not a valid branch name`
+      if (Object.values(bases).includes(name)) return 'The new branch must be different from the branch it starts from'
+      return true
+    },
+  }).then(value => value.trim())
+  const summary = proposal.repos.map(repo => `  ${repo.name}: ${bases[repo.name]} → ${branch}`).join('\n')
+  if (!(await confirm({ message: `Create these branches and start coding?\n${summary}\n`, default: true }))) return null
+  return { bases, branch }
+}
+
+module.exports = { askBranchChoice, listBranches, validBranch }