@1aboveio/skills 0.10.0

package/skills/engineering/resolve-issues/scripts/terminal-evidence-journal.mjs

@@ -0,0 +1,293 @@
+#!/usr/bin/env node
+
+import { createHash } from 'node:crypto'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+import { deliveryForUnit } from './terminal-dispositions.mjs'
+
+export const TERMINAL_EVIDENCE_SCHEMA_VERSION = 1
+export const TERMINAL_EVIDENCE_KIND = 'resolver-terminal-provider-evidence'
+export const TERMINAL_EVIDENCE_DIGEST_ALGORITHM = 'sha256-canonical-json-v1'
+const SHA = /^[0-9a-f]{40}$/i
+const CHECK_CONCLUSIONS = new Set([
+  'success', 'failure', 'cancelled', 'skipped', 'neutral', 'timed_out',
+  'action_required', 'stale', 'startup_failure',
+])
+
+const object = (value) => value != null && typeof value === 'object' && !Array.isArray(value)
+const text = (value) => typeof value === 'string' && value.trim().length > 0
+const same = (left, right) => JSON.stringify(left) === JSON.stringify(right)
+
+function exact(value, fields, label, errors) {
+  if (!object(value)) {
+    errors.push(`${label} must be an object`)
+    return false
+  }
+  const unknown = Object.keys(value).filter((field) => !fields.includes(field))
+  if (unknown.length) errors.push(`${label} has unknown field ${unknown[0]}`)
+  return true
+}
+
+function iso(value, label, errors) {
+  if (!text(value) || !Number.isFinite(Date.parse(value))) errors.push(`${label} must be an ISO timestamp`)
+}
+
+function fullSha(value, label, errors) {
+  if (!text(value) || !SHA.test(value)) errors.push(`${label} must be a full 40-character commit SHA`)
+}
+
+function positivePr(value) {
+  if (Number.isInteger(value) && value > 0) return value
+  const match = String(value ?? '').match(/^#?(\d+)$/)
+  return match && Number(match[1]) > 0 ? Number(match[1]) : null
+}
+
+function canonicalEntryBytes(entry) {
+  return `${JSON.stringify(entry)}\n`
+}
+
+export function terminalEvidenceDigest(entry) {
+  return createHash('sha256').update(canonicalEntryBytes(entry)).digest('hex')
+}
+
+export function validateTerminalEvidenceEntry(entry) {
+  const errors = []
+  if (!exact(entry, ['schemaVersion', 'kind', 'run', 'subject', 'provider', 'observations'], 'entry', errors)) return { ok: false, errors }
+  if (entry.schemaVersion !== TERMINAL_EVIDENCE_SCHEMA_VERSION) errors.push(`entry.schemaVersion must be ${TERMINAL_EVIDENCE_SCHEMA_VERSION}`)
+  if (entry.kind !== TERMINAL_EVIDENCE_KIND) errors.push(`entry.kind must be ${TERMINAL_EVIDENCE_KIND}`)
+
+  if (exact(entry.run, ['slug', 'repository', 'targetBranch'], 'entry.run', errors)) {
+    if (!text(entry.run.slug)) errors.push('entry.run.slug is required')
+    if (!text(entry.run.repository) || !/^[^/\s]+\/[^/\s]+$/.test(entry.run.repository)) errors.push('entry.run.repository must be owner/name')
+    if (!text(entry.run.targetBranch)) errors.push('entry.run.targetBranch is required')
+  }
+  if (exact(entry.subject, ['unitId', 'componentId', 'pr', 'headSha'], 'entry.subject', errors)) {
+    if (!text(entry.subject.unitId)) errors.push('entry.subject.unitId is required')
+    if (!text(entry.subject.componentId)) errors.push('entry.subject.componentId is required')
+    if (positivePr(entry.subject.pr) !== entry.subject.pr) errors.push('entry.subject.pr must be a positive integer')
+    fullSha(entry.subject.headSha, 'entry.subject.headSha', errors)
+  }
+  if (exact(entry.provider, ['id', 'observedAt'], 'entry.provider', errors)) {
+    if (!text(entry.provider.id)) errors.push('entry.provider.id is required')
+    iso(entry.provider.observedAt, 'entry.provider.observedAt', errors)
+  }
+
+  const observations = entry.observations
+  if (exact(observations, ['pullRequest', 'checks', 'targetAncestry', 'queueExecutionArtifact'], 'entry.observations', errors)) {
+    const pr = observations.pullRequest
+    if (exact(pr, ['state', 'headSha', 'mergeCommitSha', 'mergedAt'], 'entry.observations.pullRequest', errors)) {
+      if (pr.state !== 'MERGED') errors.push('entry.observations.pullRequest.state must be MERGED')
+      fullSha(pr.headSha, 'entry.observations.pullRequest.headSha', errors)
+      fullSha(pr.mergeCommitSha, 'entry.observations.pullRequest.mergeCommitSha', errors)
+      iso(pr.mergedAt, 'entry.observations.pullRequest.mergedAt', errors)
+      if (entry.subject?.headSha && pr.headSha !== entry.subject.headSha) errors.push('pull request head contradicts the bound exact head')
+    }
+
+    if (!Array.isArray(observations.checks) || observations.checks.length === 0) {
+      errors.push('entry.observations.checks must be a non-empty array')
+    } else {
+      const names = new Set()
+      for (const [index, check] of observations.checks.entries()) {
+        const label = `entry.observations.checks[${index}]`
+        if (!exact(check, ['name', 'headSha', 'conclusion', 'completedAt'], label, errors)) continue
+        if (!text(check.name)) errors.push(`${label}.name is required`)
+        else if (names.has(check.name)) errors.push(`entry.observations.checks has duplicate check ${check.name}`)
+        else names.add(check.name)
+        fullSha(check.headSha, `${label}.headSha`, errors)
+        if (entry.subject?.headSha && check.headSha !== entry.subject.headSha) errors.push(`${label}.headSha contradicts the bound exact head`)
+        if (!CHECK_CONCLUSIONS.has(check.conclusion)) errors.push(`${label}.conclusion is unsupported`)
+        if (check.completedAt !== undefined && check.completedAt !== null) iso(check.completedAt, `${label}.completedAt`, errors)
+      }
+    }
+
+    const ancestry = observations.targetAncestry
+    if (exact(ancestry, ['targetRef', 'targetHeadSha', 'mergeCommitSha', 'isAncestor', 'observedAt'], 'entry.observations.targetAncestry', errors)) {
+      if (!text(ancestry.targetRef)) errors.push('entry.observations.targetAncestry.targetRef is required')
+      fullSha(ancestry.targetHeadSha, 'entry.observations.targetAncestry.targetHeadSha', errors)
+      fullSha(ancestry.mergeCommitSha, 'entry.observations.targetAncestry.mergeCommitSha', errors)
+      if (ancestry.isAncestor !== true) errors.push('entry.observations.targetAncestry.isAncestor must be true')
+      iso(ancestry.observedAt, 'entry.observations.targetAncestry.observedAt', errors)
+      if (pr?.mergeCommitSha && ancestry.mergeCommitSha !== pr.mergeCommitSha) errors.push('target ancestry merge commit contradicts the pull request merge commit')
+    }
+    if (observations.queueExecutionArtifact !== undefined && !object(observations.queueExecutionArtifact)) {
+      errors.push('entry.observations.queueExecutionArtifact must be an object when present')
+    }
+  }
+  return { ok: errors.length === 0, errors }
+}
+
+export function validateTerminalEvidenceEnvelope(envelope) {
+  const errors = []
+  if (!exact(envelope, ['schemaVersion', 'kind', 'digestAlgorithm', 'digest', 'entry'], 'envelope', errors)) return { ok: false, errors }
+  if (envelope.schemaVersion !== TERMINAL_EVIDENCE_SCHEMA_VERSION) errors.push(`envelope.schemaVersion must be ${TERMINAL_EVIDENCE_SCHEMA_VERSION}`)
+  if (envelope.kind !== 'resolver-terminal-evidence-journal-entry') errors.push('envelope.kind must be resolver-terminal-evidence-journal-entry')
+  if (envelope.digestAlgorithm !== TERMINAL_EVIDENCE_DIGEST_ALGORITHM) errors.push(`envelope.digestAlgorithm must be ${TERMINAL_EVIDENCE_DIGEST_ALGORITHM}`)
+  const entryVerdict = validateTerminalEvidenceEntry(envelope.entry)
+  errors.push(...entryVerdict.errors)
+  const expected = object(envelope.entry) ? terminalEvidenceDigest(envelope.entry) : null
+  if (!/^[0-9a-f]{64}$/.test(envelope.digest ?? '') || envelope.digest !== expected) {
+    errors.push('envelope digest does not match the canonical entry content address')
+  }
+  return { ok: errors.length === 0, errors }
+}
+
+export function resolveTerminalEvidenceBinding(manifest, subject) {
+  if (!object(manifest) || manifest.skill !== 'resolve-issues') throw new Error('terminal evidence applies only to a resolve-issues run manifest')
+  if (!object(subject)) throw new Error('terminal evidence subject must be an object')
+  const unit = (Array.isArray(manifest.units) ? manifest.units : [])
+    .find((candidate) => candidate?.id === subject.unitId)
+  if (!unit) throw new Error(`terminal evidence unit ${subject.unitId ?? '(missing)'} is not in this run`)
+  const component = (Array.isArray(manifest.components) ? manifest.components : [])
+    .find((candidate) => candidate?.id === subject.componentId)
+  if (!component || !Array.isArray(component.units) || !component.units.includes(unit.id)) {
+    throw new Error(`terminal evidence component ${subject.componentId ?? '(missing)'} does not own unit ${unit.id}`)
+  }
+
+  let delivery = deliveryForUnit(unit, manifest)
+  let pr = positivePr(unit.pr)
+  let headSha = unit.pushedSha
+  let canonicalComponentDelivery = object(component.delivery) && delivery === component.delivery
+  if (unit.deliveryRef !== undefined) {
+    const ref = unit.deliveryRef
+    if (!object(ref) || ref.componentId !== component.id) {
+      throw new Error(`terminal evidence unit ${unit.id} is not bound to component delivery ${component.id}`)
+    }
+    delivery = object(component.delivery) && component.delivery.generation === ref.generation
+      ? component.delivery
+      : null
+    if (!delivery) throw new Error(`terminal evidence unit ${unit.id} has a stale canonical component delivery binding`)
+    pr = positivePr(delivery.pr)
+    headSha = delivery.authorizedHeadSha
+    canonicalComponentDelivery = true
+  }
+  if (pr == null) throw new Error(`terminal evidence delivery for unit ${unit.id} has no positive PR identity`)
+  if (!text(headSha) || !SHA.test(headSha)) throw new Error(`terminal evidence delivery for unit ${unit.id} has no full exact head SHA`)
+
+  return {
+    unit,
+    component,
+    delivery,
+    canonicalComponentDelivery,
+    subject: { unitId: unit.id, componentId: component.id, pr, headSha },
+  }
+}
+
+function boundEntry(manifest, observation) {
+  if (!object(manifest) || manifest.skill !== 'resolve-issues') throw new Error('terminal evidence applies only to a resolve-issues run manifest')
+  if (!text(manifest.runSlug) || !text(manifest.repository) || !text(manifest.targetBranch)) {
+    throw new Error('terminal evidence requires run slug, repository, and target branch bindings')
+  }
+  if (!object(observation)) throw new Error('terminal evidence observation must be an object')
+  const binding = resolveTerminalEvidenceBinding(manifest, observation)
+  const expectedTargetRef = `origin/${manifest.targetBranch}`
+  if (observation.pullRequest?.headSha !== binding.subject.headSha) {
+    throw new Error(`terminal evidence pull request head does not match delivery for unit ${binding.unit.id} exact head`)
+  }
+  if (observation.targetAncestry?.targetRef !== expectedTargetRef) throw new Error(`terminal evidence target ancestry must bind ${expectedTargetRef}`)
+
+  return {
+    schemaVersion: TERMINAL_EVIDENCE_SCHEMA_VERSION,
+    kind: TERMINAL_EVIDENCE_KIND,
+    run: { slug: manifest.runSlug, repository: manifest.repository, targetBranch: manifest.targetBranch },
+    subject: binding.subject,
+    provider: structuredClone(observation.provider),
+    observations: {
+      pullRequest: structuredClone(observation.pullRequest),
+      checks: structuredClone(observation.checks),
+      targetAncestry: structuredClone(observation.targetAncestry),
+      ...(observation.queueExecutionArtifact !== undefined
+        ? { queueExecutionArtifact: structuredClone(observation.queueExecutionArtifact) }
+        : {}),
+    },
+  }
+}
+
+export function defaultTerminalEvidenceDirectory(env = process.env) {
+  if (text(env.RESOLVER_TERMINAL_EVIDENCE_DIR)) return path.resolve(env.RESOLVER_TERMINAL_EVIDENCE_DIR)
+  const stateHome = text(env.XDG_STATE_HOME) ? env.XDG_STATE_HOME : path.join(env.HOME || os.homedir(), '.local', 'state')
+  return path.resolve(stateHome, 'resolver-terminal-evidence')
+}
+
+export function appendTerminalEvidence(manifest, observation, { directory = defaultTerminalEvidenceDirectory() } = {}) {
+  const entry = boundEntry(manifest, observation)
+  const verdict = validateTerminalEvidenceEntry(entry)
+  if (!verdict.ok) throw new Error(`terminal evidence is invalid: ${verdict.errors[0]}`)
+  const digest = terminalEvidenceDigest(entry)
+  const envelope = {
+    schemaVersion: TERMINAL_EVIDENCE_SCHEMA_VERSION,
+    kind: 'resolver-terminal-evidence-journal-entry',
+    digestAlgorithm: TERMINAL_EVIDENCE_DIGEST_ALGORITHM,
+    digest,
+    entry,
+  }
+  const bytes = `${JSON.stringify(envelope, null, 2)}\n`
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 })
+  const destination = path.join(directory, `${digest}.json`)
+  let descriptor = null
+  try {
+    descriptor = fs.openSync(destination, 'wx', 0o444)
+    fs.writeFileSync(descriptor, bytes, 'utf8')
+    fs.fsyncSync(descriptor)
+  } catch (error) {
+    if (error.code !== 'EEXIST') throw error
+    const existing = fs.readFileSync(destination, 'utf8')
+    if (existing !== bytes) throw new Error(`terminal evidence content-address collision or tampering at ${destination}`)
+  } finally {
+    if (descriptor != null) fs.closeSync(descriptor)
+  }
+  fs.chmodSync(destination, 0o444)
+  return { digest, path: destination, entry }
+}
+
+export function readTerminalEvidence(file) {
+  const envelope = JSON.parse(fs.readFileSync(file, 'utf8'))
+  const verdict = validateTerminalEvidenceEnvelope(envelope)
+  if (!verdict.ok) throw new Error(`terminal evidence journal entry is invalid: ${verdict.errors[0]}`)
+  const basename = path.basename(file)
+  if (basename !== `${envelope.digest}.json`) throw new Error('terminal evidence filename does not match its content address')
+  return envelope
+}
+
+function parseArgs(argv) {
+  const command = argv[0]
+  const options = {}
+  const positional = []
+  for (let index = 1; index < argv.length; index += 1) {
+    const argument = argv[index]
+    if (['--manifest', '--input', '--dir'].includes(argument)) options[argument.slice(2)] = argv[++index]
+    else positional.push(argument)
+  }
+  return { command, options, positional }
+}
+
+export function runTerminalEvidenceJournalCli(argv) {
+  const { command, options, positional } = parseArgs(argv)
+  try {
+    if (['--help', '-h', 'help'].includes(command)) {
+      process.stdout.write('usage: terminal-evidence-journal.mjs append --manifest <run.json> --input <observation.json> [--dir <journal-dir>] | validate <entry.json>\n')
+      return 0
+    }
+    if (command === 'append') {
+      if (!options.manifest || !options.input) throw new Error('append requires --manifest <run.json> --input <observation.json> [--dir <journal-dir>]')
+      const manifest = JSON.parse(fs.readFileSync(options.manifest, 'utf8'))
+      const observation = JSON.parse(fs.readFileSync(options.input, 'utf8'))
+      const result = appendTerminalEvidence(manifest, observation, options.dir ? { directory: path.resolve(options.dir) } : {})
+      process.stdout.write(`${JSON.stringify(result, null, 2)}\n`)
+      return 0
+    }
+    if (command === 'validate') {
+      if (positional.length !== 1) throw new Error('validate requires <content-addressed-entry.json>')
+      const envelope = readTerminalEvidence(positional[0])
+      process.stdout.write(`terminal-evidence-journal: valid ${envelope.digest}\n`)
+      return 0
+    }
+    throw new Error('usage: terminal-evidence-journal.mjs append --manifest <run.json> --input <observation.json> [--dir <journal-dir>] | validate <entry.json>')
+  } catch (error) {
+    process.stderr.write(`terminal-evidence-journal: ${error.message}\n`)
+    return 2
+  }
+}
+
+if (isMainModule(import.meta.url)) process.exitCode = runTerminalEvidenceJournalCli(process.argv.slice(2))

package/skills/engineering/resolve-issues/scripts/unit-kind.mjs

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+
+import fs, { realpathSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+export const UNIT_KINDS = ['implementation', 'external-verification', 'human-decision', 'prerequisite']
+
+const nonEmpty = (value) => typeof value === 'string' && value.trim().length > 0
+
+export const EVIDENCE_LIFECYCLE_CLASSES = ['ordinary', 'evidence-authorization']
+
+const EVIDENCE_SEMANTICS = /\b(authorization|authorisation|required[- ]checks?|admission|delivery evidence|enqueue|queue[- ]head|synthetic queue|mergeable|target[- ]branch ancestry)\b/i
+const EVIDENCE_CONTROL_SURFACES = /(?:^|\/)resolve-issues\/scripts\/(?:unit-kind|spawn-contract|evidence-lifecycle-contract|required-check-plan|combine-and-verify|component-candidate|exact-head(?:-ci|-github-provider)?|watch-delivery|finalize)(?:\.|\/|$)/i
+const EVIDENCE_DOCTRINE_SURFACES = /(?:^|\/)resolve-issues\/(?:SKILL\.md|references\/(?:breaker|deliverables|delivery|evidence-lane|exact-head-ci|fan-out|finalization|high-risk|intake|integration-gate|interference|loop|pre-flight(?:-[^/]+)?|regression-checklist|run-state|spawn-contract|why)\.md)$/i
+
+const isEvidenceLifecycleSurface = (path) => (
+  EVIDENCE_CONTROL_SURFACES.test(path) || EVIDENCE_DOCTRINE_SURFACES.test(path)
+)
+
+function classifyEvidenceLifecycle(input, text) {
+  const signals = []
+  const declaration = input.declaredScope
+  if (declaration !== undefined) {
+    if (declaration == null || typeof declaration !== 'object' || Array.isArray(declaration)
+        || !EVIDENCE_LIFECYCLE_CLASSES.includes(declaration.classification)) {
+      signals.push({ type: 'unknown-declared-scope', source: 'declaredScope' })
+    } else if (declaration.classification === 'evidence-authorization') {
+      signals.push({ type: 'declared-lifecycle-scope', source: 'declaredScope' })
+    }
+    if (nonEmpty(declaration?.summary) && EVIDENCE_SEMANTICS.test(declaration.summary)) {
+      signals.push({ type: 'declared-lifecycle-semantics', source: 'declaredScope.summary' })
+    }
+  }
+
+  if (input.changedSurfaces !== undefined && !Array.isArray(input.changedSurfaces)) {
+    signals.push({ type: 'unknown-changed-surface', source: 'changedSurfaces' })
+  } else {
+    for (const [index, surface] of (input.changedSurfaces || []).entries()) {
+      if (surface == null || typeof surface !== 'object' || Array.isArray(surface)
+          || !nonEmpty(surface.path) || !EVIDENCE_LIFECYCLE_CLASSES.includes(surface.classification)) {
+        signals.push({ type: 'unknown-changed-surface', source: `changedSurfaces[${index}]` })
+        continue
+      }
+      if (surface.classification === 'evidence-authorization') {
+        signals.push({ type: 'declared-lifecycle-surface', source: surface.path })
+      }
+      if (isEvidenceLifecycleSurface(surface.path)) {
+        signals.push({ type: 'sensitive-changed-surface', source: surface.path })
+      }
+    }
+  }
+
+  if (EVIDENCE_SEMANTICS.test(text)) signals.push({ type: 'lifecycle-semantics', source: 'title/body' })
+  const required = signals.length > 0
+  return {
+    classification: required ? 'evidence-authorization' : 'ordinary',
+    required,
+    denyByDefault: true,
+    signals,
+  }
+}
+
+const SIGNALS = [
+  {
+    type: 'physical-presence',
+    pattern: /\b(physically present|physical presence|on[- ]site|in person|live (?:application|terminal|device|lane) operator)\b/i,
+    recommendation: 'external-verification',
+  },
+  {
+    type: 'external-dispatch',
+    pattern: /\b(dispatch|send)\b[^.\n]{0,80}\b(external|operator|technician|auditor)\b|\bexternal dispatch\b/i,
+    recommendation: 'external-verification',
+  },
+  {
+    type: 'provider-observation',
+    pattern: /\b(provider|acquirer|issuer|third[- ]party)\b[^.\n]{0,100}\b(observe|observations?|attest|certif(?:y|ication))\b|\b(observe|observations?)\b[^.\n]{0,100}\b(provider|acquirer|issuer|third[- ]party)\b/i,
+    recommendation: 'external-verification',
+  },
+  {
+    type: 'third-party-approval',
+    pattern: /\b(provider|acquirer|issuer|third[- ]party|legal|regulator)\b[^.\n]{0,100}\b(approve|approval|sign[- ]off|consent)\b/i,
+    recommendation: 'external-verification',
+  },
+  {
+    type: 'human-decision',
+    pattern: /\b(product owner|human|legal|compliance|stakeholder)\b[^.\n]{0,100}\b(decide|decision|choose|select|approve)\b|\b(decide|decision|choose)\b[^.\n]{0,100}\b(policy|option|whether)\b/i,
+    recommendation: 'human-decision',
+  },
+  {
+    type: 'credentials',
+    pattern: /\b(credential|credentials|api key|secret|certificate|production access)\b/i,
+    recommendation: 'prerequisite',
+  },
+  {
+    type: 'hardware',
+    pattern: /\b(hardware|security key|physical terminal|device)\b/i,
+    recommendation: 'prerequisite',
+  },
+  {
+    type: 'prerequisite-input',
+    pattern: /\b(obtain|provision|procure|provide|land)\b[^.\n]{0,100}\b(before|prerequisite|input|required)\b|\b(before .* can begin|before implementation)\b/i,
+    recommendation: 'prerequisite',
+  },
+]
+
+function recommend(signals) {
+  const kinds = new Set(signals.map((signal) => signal.recommendation))
+  if (kinds.has('human-decision')) return 'human-decision'
+  if (kinds.has('external-verification')) return 'external-verification'
+  if (kinds.has('prerequisite')) return 'prerequisite'
+  return 'implementation'
+}
+
+export function classifyUnitIntake(input = {}) {
+  if (input == null || typeof input !== 'object' || Array.isArray(input)) {
+    throw new TypeError('intake must be a JSON object')
+  }
+  if (input.selectedKind !== undefined && !UNIT_KINDS.includes(input.selectedKind)) {
+    throw new TypeError(`selectedKind must be one of ${UNIT_KINDS.join('|')}`)
+  }
+
+  const text = `${nonEmpty(input.title) ? input.title : ''}\n${nonEmpty(input.body) ? input.body : ''}`
+  const signals = SIGNALS
+    .filter((signal) => signal.pattern.test(text))
+    .map(({ type, recommendation }) => ({ type, recommendation }))
+  const recommendedKind = recommend(signals)
+  const evidenceLifecycle = classifyEvidenceLifecycle(input, text)
+  const unitKind = input.selectedKind ?? recommendedKind
+  const required = recommendedKind !== 'implementation' || unitKind !== 'implementation'
+  const confirmed = required && nonEmpty(input.confirmedBy) && nonEmpty(input.confirmedAt)
+  const confirmation = {
+    required,
+    status: required ? (confirmed ? 'confirmed' : 'pending') : 'not-required',
+    kind: unitKind,
+    ...(confirmed ? { confirmedBy: input.confirmedBy.trim(), confirmedAt: input.confirmedAt.trim() } : {}),
+  }
+
+  return { unitKind, recommendedKind, signals, confirmation, evidenceLifecycle }
+}
+
+export function intakePatch(input = {}) {
+  const result = classifyUnitIntake(input)
+  return {
+    unitKind: result.unitKind,
+    kindRecommendation: {
+      kind: result.recommendedKind,
+      signals: result.signals,
+    },
+    kindConfirmation: result.confirmation,
+    evidenceLifecycle: result.evidenceLifecycle,
+  }
+}
+
+function usage() {
+  return 'usage: unit-kind.mjs classify --stdin\n'
+}
+
+function main(argv = process.argv.slice(2)) {
+  if (argv.length === 1 && ['--help', '-h', 'help'].includes(argv[0])) {
+    process.stdout.write(usage())
+    return 0
+  }
+  if (argv.length !== 2 || argv[0] !== 'classify' || argv[1] !== '--stdin') {
+    process.stderr.write(usage())
+    return 2
+  }
+  try {
+    const input = JSON.parse(fs.readFileSync(0, 'utf8'))
+    process.stdout.write(`${JSON.stringify(intakePatch(input), null, 2)}\n`)
+    return 0
+  } catch (error) {
+    process.stderr.write(`unit-kind: ${error.message}\n`)
+    return 2
+  }
+}
+
+let launchedDirectly = false
+let mainModuleError = null
+try {
+  const { isMainModule } = await import('../../engineering-runtime/scripts/main-module.mjs')
+  if (typeof isMainModule !== 'function') throw new Error('main-module.mjs does not export isMainModule')
+  launchedDirectly = isMainModule(import.meta.url)
+} catch (error) {
+  mainModuleError = error
+  try {
+    launchedDirectly = realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))
+  } catch {
+    launchedDirectly = false
+  }
+}
+
+if (launchedDirectly && mainModuleError) {
+  console.error(`unit-kind: cannot load engineering-runtime main-module helper: ${mainModuleError.message}`)
+  process.exitCode = 1
+} else if (launchedDirectly) {
+  process.exitCode = main()
+}

package/skills/engineering/resolve-issues/scripts/unit-lifecycle.mjs

@@ -0,0 +1,127 @@
+import { UNIT_KINDS } from './unit-kind.mjs'
+
+export const EXTERNAL_COMPLETION_SOURCES = ['authorized-actor-observation', 'third-party-decision']
+
+const nonEmpty = (value) => typeof value === 'string' && value.trim().length > 0
+const isObject = (value) => value != null && typeof value === 'object' && !Array.isArray(value)
+const stringList = (value) => Array.isArray(value) && value.length > 0 && value.every(nonEmpty)
+
+export function effectiveUnitKind(unit) {
+  return UNIT_KINDS.includes(unit?.unitKind) ? unit.unitKind : 'implementation'
+}
+
+function validateConfirmation(unit, label, errors) {
+  const recommendation = isObject(unit.kindRecommendation) ? unit.kindRecommendation.kind : 'implementation'
+  const kind = effectiveUnitKind(unit)
+  const required = kind !== 'implementation' || recommendation !== 'implementation'
+  if (!required) return
+  const confirmation = unit.kindConfirmation
+  if (!isObject(confirmation) || confirmation.status !== 'confirmed') {
+    errors.push(`${label}.kindConfirmation must be explicitly confirmed before ${kind} enters the roster`)
+    return
+  }
+  if (confirmation.kind !== kind) errors.push(`${label}.kindConfirmation.kind must match unitKind ${kind}`)
+  if (!nonEmpty(confirmation.confirmedBy)) errors.push(`${label}.kindConfirmation.confirmedBy is required`)
+  if (!nonEmpty(confirmation.confirmedAt)) errors.push(`${label}.kindConfirmation.confirmedAt is required`)
+}
+
+function validateExternalProtocol(protocol, label, errors) {
+  if (!isObject(protocol)) {
+    errors.push(`${label}.externalProtocol is required for external-verification`)
+    return
+  }
+  for (const field of ['prerequisites', 'authorizedActors', 'allowedOperations']) {
+    if (!stringList(protocol[field])) errors.push(`${label}.externalProtocol.${field} must be a non-empty string array`)
+  }
+  for (const field of ['environmentIdentity', 'stopPolicy', 'retryPolicy', 'completionSource']) {
+    if (!nonEmpty(protocol[field])) errors.push(`${label}.externalProtocol.${field} is required`)
+  }
+  if (!EXTERNAL_COMPLETION_SOURCES.includes(protocol.completionSource)) {
+    errors.push(`${label}.externalProtocol.completionSource must be one of ${EXTERNAL_COMPLETION_SOURCES.join('|')}`)
+  }
+  if (!isObject(protocol.evidenceSchema) || !stringList(protocol.evidenceSchema.required)) {
+    errors.push(`${label}.externalProtocol.evidenceSchema.required must be a non-empty string array`)
+  }
+}
+
+function externalCompletionErrors(unit, label) {
+  const errors = []
+  const completion = unit.externalCompletion
+  if (completion === undefined || completion === null) return errors
+  const protocol = unit.externalProtocol
+  if (!isObject(completion)) return [`${label}.externalCompletion must be an object`]
+  if (!isObject(protocol)) return [`${label}.externalCompletion cannot be checked without externalProtocol`]
+  if (completion.source !== protocol.completionSource) errors.push(`${label}.externalCompletion.source must match externalProtocol.completionSource`)
+  if (!Array.isArray(protocol.authorizedActors) || !protocol.authorizedActors.includes(completion.actor)) {
+    errors.push(`${label}.externalCompletion.actor must be one of externalProtocol.authorizedActors`)
+  }
+  if (completion.environmentIdentity !== protocol.environmentIdentity) {
+    errors.push(`${label}.externalCompletion.environmentIdentity must match externalProtocol.environmentIdentity`)
+  }
+  if (!Array.isArray(protocol.allowedOperations) || !protocol.allowedOperations.includes(completion.operation)) {
+    errors.push(`${label}.externalCompletion.operation must be one of externalProtocol.allowedOperations`)
+  }
+  if (!nonEmpty(completion.observedAt)) errors.push(`${label}.externalCompletion.observedAt is required`)
+  if (!isObject(completion.evidence)) {
+    errors.push(`${label}.externalCompletion.evidence must satisfy externalProtocol.evidenceSchema`)
+  } else {
+    const missing = (protocol.evidenceSchema?.required ?? []).filter((key) => !nonEmpty(completion.evidence[key]))
+    if (missing.length) errors.push(`${label}.externalCompletion.evidenceSchema missing required evidence: ${missing.join(', ')}`)
+  }
+  return errors
+}
+
+export function validateUnitKind(unit, label = 'unit') {
+  const errors = []
+  if (!isObject(unit)) return [`${label} must be an object`]
+  if (unit.unitKind !== undefined && !UNIT_KINDS.includes(unit.unitKind)) {
+    errors.push(`${label}.unitKind must be one of ${UNIT_KINDS.join('|')}`)
+    return errors
+  }
+  if (unit.kindRecommendation !== undefined) {
+    if (!isObject(unit.kindRecommendation) || !UNIT_KINDS.includes(unit.kindRecommendation.kind)) {
+      errors.push(`${label}.kindRecommendation.kind must be one of ${UNIT_KINDS.join('|')}`)
+    } else if (!Array.isArray(unit.kindRecommendation.signals)) {
+      errors.push(`${label}.kindRecommendation.signals must be an array`)
+    }
+  }
+  validateConfirmation(unit, label, errors)
+  const kind = effectiveUnitKind(unit)
+  if (kind === 'external-verification') {
+    validateExternalProtocol(unit.externalProtocol, label, errors)
+    errors.push(...externalCompletionErrors(unit, label))
+  }
+  if (kind !== 'implementation' && nonEmpty(unit.pr)) {
+    errors.push(`${label}: ${kind} may reference artifacts but may not own an implementation PR`)
+  }
+  if (kind !== 'implementation' && (unit.status === 'merge-ready' || unit.delivery !== undefined || unit.lastVerdict !== undefined)) {
+    errors.push(`${label}: ${kind} never uses code delivery or review PASS; an artifact PASS is not ${kind} completion`)
+  }
+  if (unit.completionDependsOn !== undefined && (!Array.isArray(unit.completionDependsOn) || !unit.completionDependsOn.every(nonEmpty))) {
+    errors.push(`${label}.completionDependsOn must be an array of non-empty unit ids`)
+  }
+  return errors
+}
+
+export function unitKindComplete(unit) {
+  const kind = effectiveUnitKind(unit)
+  if (kind === 'implementation') return false
+  if (kind === 'external-verification') {
+    const protocolErrors = []
+    validateExternalProtocol(unit.externalProtocol, 'unit', protocolErrors)
+    return protocolErrors.length === 0 && externalCompletionErrors(unit, 'unit').length === 0 && isObject(unit.externalCompletion)
+  }
+  if (kind === 'human-decision') {
+    return isObject(unit.humanDecision) && nonEmpty(unit.humanDecision.decision)
+      && nonEmpty(unit.humanDecision.decidedBy) && nonEmpty(unit.humanDecision.decidedAt)
+  }
+  return isObject(unit.prerequisiteCompletion) && nonEmpty(unit.prerequisiteCompletion.source)
+    && nonEmpty(unit.prerequisiteCompletion.completedAt) && nonEmpty(unit.prerequisiteCompletion.evidence)
+}
+
+export function completionBlockers(manifest, unit) {
+  const units = Array.isArray(manifest?.units) ? manifest.units : []
+  const byId = new Map(units.filter(isObject).map((entry) => [entry.id, entry]))
+  return (Array.isArray(unit?.completionDependsOn) ? unit.completionDependsOn : [])
+    .filter((id) => !unitKindComplete(byId.get(id)))
+}