@1aboveio/skills 0.10.0

package/skills/engineering/resolve-issues/scripts/spawn-contract.mjs

@@ -0,0 +1,290 @@
+// NOT A CLI. Running this file directly does nothing — no output, exit 0 — because it has no
+// entry point. `run-state.mjs spawn-contract <slug> <unitId> [--kind producer|fix|review] [--json]` is the entry point,
+// and it does work this module cannot: it derives scheduler/manifest context this file never sees.
+//
+// A guard that says so out loud was tried and reverted. It has to import the shared main-module
+// helper from `engineering-runtime`, and `run-state.mjs` imports THIS file at load — so the new
+// edge changed which module a runtime-missing install reports first, turning an actionable "the
+// coherence contract is missing" into "a helper is missing". Degrading an operator-facing
+// fail-closed diagnostic to catch an authoring mistake is the wrong trade; the docs now link the
+// command text at `run-state.mjs`, and a test pins that they keep doing so.
+// The spawn contract, rendered from state instead of composed in prose.
+//
+// Why this is a command and not a paragraph. Measured over 33 Pi sessions and 163
+// producer spawns (2026-08-04): the producer spawn prompt is composed ONCE per run and
+// then repeated for every unit, never re-derived from doctrine. **10 of 17 sessions with
+// 4+ producer spawns vary by at most one gate across the entire run** — one session sat
+// at exactly 2 of 5 gates for 27 consecutive spawns; another named all 5 eighteen times;
+// a third named none of them nine times. Whatever the first composition happened to
+// contain, every later unit in that run inherited.
+//
+// So the failure is not that an orchestrator disagrees with the doctrine. It is that the
+// doctrine is consulted once, at the first spawn, and the template then drifts free of
+// it — and where it moves it more often decays than improves (7 sessions down, 3 up, 7
+// flat), with the decays on the LONGEST runs: 4 gates → 1, and 2 → 1 across a 33-spawn
+// session. That is the shape of context pressure eroding a remembered template, and no
+// amount of additional prose fixes a template that is never re-read.
+//
+// The consequence is concrete rather than stylistic. `coverage-checklist.mjs validate`
+// answers a strictly weaker question without `--diff` (a missing locator warns instead
+// of blocking), so a producer that omits the flag hands over a green the reviewer's run
+// turns red — 1above-official #35: producer `validate --root .` passed, reviewer
+// `validate --diff` found 9 PASS rows with no resolving locator, and the unit bought an
+// evidence round for the difference. `--diff` appeared in 10% of producer spawns.
+//
+// Rendering the contract makes spawn 1 and spawn 33 byte-identical, and makes the gate
+// list a property of the RUN rather than of whichever composition survived. It is also a
+// net deletion from `loop.md`, which now points here instead of describing the contract.
+//
+// What this does NOT do: it does not spawn anything, and it does not replace reading
+// `implement-and-pr`/`review-pr`. It renders the wrapper whose whole job is to make the
+// leaf agent read those skills at an absolute path, with the run's own facts filled in.
+
+import { effectiveUnitKind } from './unit-lifecycle.mjs'
+import { validateEvidenceLifecycleContract } from './evidence-lifecycle-contract.mjs'
+
+const isObject = (v) => v != null && typeof v === 'object' && !Array.isArray(v)
+const nonEmpty = (v) => typeof v === 'string' && v.trim().length > 0
+
+export const SPAWN_KINDS = ['producer', 'fix', 'review']
+
+// The gates a producer/fix close-out owes, each with the flag that makes it decide
+// rather than merely run. The flags are the entire point of the list: a gate named
+// without them is the shape this file exists to stop being repeated.
+//
+// `<skillsRoot>/<owning-skill>/scripts/…` — never a CWD-relative `scripts/…` and never
+// found by searching, which the spawn contract already forbids and which is exactly what
+// a leaf agent does when handed a bare skill name.
+export const PRODUCER_GATES = [
+  { skill: 'ensure-coverage', script: 'coverage-checklist.mjs', args: 'validate <checklist.md> --diff <merge-base>', why: 'without --diff a missing locator WARNS instead of blocking, so this passes where the reviewer\'s run fails' },
+  { skill: 'ensure-coverage', script: 'lint-tests.mjs', args: '--rules no-skip,no-fixed-timeout,no-empty-test,mock-internal-seam --diff <merge-base>', why: 'PR-lane; then re-run bare for the whole-tree mock-internal-seam sweep' },
+  { skill: 'ensure-coverage', script: 'coverage-ledger.mjs', args: 'validate', why: 'breadth — the surface inventory must not have drifted' },
+  { skill: 'review-pr', script: 'scan-diff.mjs', args: '(git diff <merge-base>...HEAD | node …)', why: 'report the decidable findings channel VERBATIM; every hit is a zero-tolerance blocker' },
+]
+
+// What the manifest structurally cannot hold, per spawn kind. These are not omissions to
+// be fixed by storing more — findings are prose the reviewer returns, CI failures arrive
+// after the spawn is composed, and the work item lives in the issue. They are named here
+// so a caller pasting a rendered contract cannot mistake it for the whole prompt.
+export const APPENDS = {
+  producer: [
+    'THE WORK ITEM — what to build, from the issue body and its acceptance criteria. The contract above says how to work, never what to work on.',
+    'The approved test criteria, or the design/contract doc, where one exists.',
+  ],
+  fix: [
+    'THE REVIEWER\'S FINDINGS, VERBATIM — every one, with its `file:line`, confidence and `theme`. A fix round without them is a spawn told to fix nothing; the manifest records the verdict, never the findings.',
+    'Every CI failure known at spawn time, including one carried from an earlier round whose CI landed after that round\'s fix had started.',
+    'The invariant CLASS each fix must close — not the counterexample cited. A fix that closes only the instance is reconciled `Partially resolved` and buys another round.',
+  ],
+  review: [
+    'The PR ref and the exact head SHA to review, with a stop-if-HEAD-moved clause — a verdict against a moved head is not a verdict on what you asked about.',
+    'How the verdict may be posted — ask `run-state.mjs approval-gate <slug>` FIRST. Exit 1 means the reviewer posts a COMMENT and merges nothing, because on an auto-merging repo an approving review IS the merge.',
+    'The prior findings to reconcile, on any round after the first.',
+  ],
+}
+
+const effortOf = (models, slot) => {
+  const e = models?.[`${slot}Effort`]
+  return nonEmpty(e) ? e : 'high'
+}
+
+// Env vars injected into every producer/review/fix child so a sandboxed spawn can
+// report the confirmed slot without reading harness-private PI_* vars (#792 /
+// issue-664 / identity#669). The orchestrator's launch id remains authoritative for
+// the diversity guard when the child cannot read these or returns unknown.
+export const SLOT_ENV = {
+  model: 'RESOLVE_SLOT_MODEL',
+  effort: 'RESOLVE_SLOT_EFFORT',
+}
+
+// Whether THIS harness can put env vars into a subagent. Read from the capabilities
+// pre-flight step 0 recorded, never guessed from the model ids: a harness that spawns by
+// tool call with no env parameter (Claude Code's `Agent`) cannot, and one that spawns a
+// process it configures (Pi's `subagent_spawn`) can. Unknown capabilities fall back to the
+// injecting shape, which is the historical behaviour and merely renders one extra sentence
+// where it does not apply — whereas withholding it on a harness that CAN inject would drop
+// a real guard.
+export function envInjectionAvailable(manifest) {
+  const tools = manifest?.currentTurnCapabilities?.nativeTools
+  if (!Array.isArray(tools) || !tools.length) return true
+  const NO_ENV_SPAWNERS = ['Agent', 'Task']
+  const ENV_SPAWNERS = ['subagent_spawn', 'subagent_spawn_batch']
+  if (tools.some((t) => ENV_SPAWNERS.includes(t))) return true
+  if (tools.some((t) => NO_ENV_SPAWNERS.includes(t))) return false
+  return true
+}
+
+function unitOf(manifest, unitId) {
+  const units = Array.isArray(manifest?.units) ? manifest.units.filter(isObject) : []
+  return units.find((u) => u.id === unitId) || null
+}
+
+function validatedLifecycleContract(unit) {
+  if (unit?.evidenceLifecycle?.required !== true) return null
+  if (!isObject(unit.evidenceLifecycleContract)) {
+    throw new Error(`${unit.id} is classified evidence-authorization and requires evidenceLifecycleContract before implementation begins`)
+  }
+  const result = validateEvidenceLifecycleContract(unit.evidenceLifecycleContract)
+  if (!result.ok) {
+    throw new Error(`${unit.id} evidenceLifecycleContract is invalid: ${result.errors.join('; ')}`)
+  }
+  return unit.evidenceLifecycleContract
+}
+
+// Round count drives the two conditionals a leaf agent cannot compute for itself.
+const roundsOf = (unit) => (Array.isArray(unit?.rounds) ? unit.rounds.length : 0)
+
+// Everything the renderer could not fill from state, collected rather than guessed. A
+// contract with a hole in it is still worth printing — the hole is the actionable part,
+// and inventing a plausible value for `skillsRoot` is how a spawn silently reads nothing.
+function gaps(manifest, unit, kind) {
+  const out = []
+  if (!nonEmpty(manifest?.skillsRoot)) out.push('skillsRoot — the ABSOLUTE skills directory. Without it the leaf agent cannot read its skill and degrades to a memory-reconstructed lookalike. Set it: run-state.mjs set <slug> skillsRoot /abs/path')
+  if (!nonEmpty(unit?.workspacePath)) out.push('units[].workspacePath — the unit\'s OWN tree. Absent, the spawn inherits the orchestrator\'s cwd and writes into the checkout you are coordinating from.')
+  const slot = kind === 'review' ? 'review' : 'implementation'
+  if (!nonEmpty(manifest?.models?.[slot])) out.push(`models.${slot} — the confirmed model for this slot (pre-flight step 4).`)
+  if (!nonEmpty(manifest?.targetBranch)) out.push('targetBranch — settled at pre-flight from fetched remote heads.')
+  return out
+}
+
+export function renderSpawnContract(manifest = {}, unitId, { kind = 'producer' } = {}) {
+  if (!SPAWN_KINDS.includes(kind)) throw new Error(`kind must be one of ${SPAWN_KINDS.join('|')}`)
+  const m = isObject(manifest) ? manifest : {}
+  const unit = unitOf(m, unitId)
+  if (!unit) throw new Error(`no unit ${unitId} in this run`)
+  const unitKind = effectiveUnitKind(unit)
+  if (unitKind !== 'implementation') {
+    throw new Error(`only implementation units enter the code loop; ${unitId} is ${unitKind} and must be completed by its recorded non-code protocol`)
+  }
+  const lifecycleContract = validatedLifecycleContract(unit)
+
+  const root = nonEmpty(m.skillsRoot) ? m.skillsRoot.replace(/\/+$/, '') : '<skillsRoot — NOT RECORDED>'
+  const slot = kind === 'review' ? 'review' : 'implementation'
+  const model = nonEmpty(m.models?.[slot]) ? m.models[slot] : `<models.${slot} — NOT RECORDED>`
+  const effort = effortOf(m.models, slot)
+  const ws = nonEmpty(unit.workspacePath) ? unit.workspacePath : '<units[].workspacePath — NOT RECORDED>'
+  const target = nonEmpty(m.targetBranch) ? m.targetBranch : '<targetBranch — NOT RECORDED>'
+  const rounds = roundsOf(unit)
+  const skill = kind === 'review' ? 'review-pr' : 'implement-and-pr'
+
+  const L = []
+  L.push(`SPAWN CONTRACT — ${kind} · unit ${unit.id} · run ${m.runSlug ?? '<slug>'}`)
+  L.push(`model ${model} @ ${effort}   ·   cwd ${ws}`)
+  // The header states what the launcher must DO. On a harness with no env parameter there is
+  // nothing to set, and printing the vars anyway invites the orchestrator to believe it did.
+  L.push(envInjectionAvailable(manifest)
+    ? `env ${SLOT_ENV.model}=${model}  ${SLOT_ENV.effort}=${effort}`
+    : 'env —  this harness cannot inject env into a subagent; the prompt asks for a session-identity read-back instead')
+  L.push('Paste the block below as the spawn prompt. Rendered from state — do not retype it,')
+  L.push('and do not trim it: every clause here fails SILENTLY when dropped.')
+  L.push('─'.repeat(78))
+  L.push('')
+
+  // (a) read the skill, absolute.
+  L.push(`Read \`${root}/${skill}/SKILL.md\` (absolute path — do NOT search for it) and follow it end-to-end. Do not improvise, and do not spawn agents of your own.`)
+  L.push('')
+  L.push(`Work item: ${unit.id}${nonEmpty(unit.pr) ? ` · PR ${unit.pr}` : ''}${nonEmpty(unit.branch) ? ` · branch ${unit.branch}` : ''}. Target branch: ${target}.`)
+  L.push(`Work in ${ws} — this unit's own tree. Never the orchestrator's checkout.`)
+  // (d) model + effort — the read-back that makes "no silent fallback" checkable.
+  //
+  // Env injection is NOT universal. Some harnesses (Pi) launch children with an env the
+  // orchestrator controls; others (Claude Code's `Agent` tool) expose no env parameter at
+  // all, and the injection clause is then an instruction that CANNOT be followed. Rendering
+  // it anyway is worse than saying nothing: the child reports the vars empty, the guard
+  // degrades to an honour-system self-report, and nothing in the run says the mechanism
+  // never ran. fmm-express epic-894 rendered it to 7/7 spawns on Claude Code; all seven came
+  // back empty and every prompt had to be hand-patched after the fact.
+  //
+  // Pre-flight step 0 already records `currentTurnCapabilities` for exactly this kind of
+  // adaptation, so consult it rather than assuming the Pi shape.
+  L.push(envInjectionAvailable(manifest)
+    ? `Slot env (inject into the child process): ${SLOT_ENV.model}=${model} ${SLOT_ENV.effort}=${effort}. Report these back as the model you ran on; if you cannot read them, say so — do not invent a model string.`
+    : `Model for this spawn: ${model} @ ${effort}. This harness cannot inject env into a subagent, so there is no slot variable to read: report YOUR OWN session's model identity instead, and say so plainly if you cannot determine it. Never invent a model string, and never echo the id above as if you had read it back — the whole point of the read-back is that it can disagree with what was requested.`)
+
+  if (lifecycleContract) {
+    L.push('')
+    L.push('Evidence lifecycle contract: VALIDATED before implementation. Build/review every discovered condition against this exact artifact:')
+    L.push('```json')
+    L.push(JSON.stringify(lifecycleContract, null, 2))
+    L.push('```')
+    L.push('Check the implementation against this lifecycle contract. The artifact does not replace independent code review or provider evidence.')
+  }
+
+  if (kind === 'review') {
+    L.push('')
+    L.push(`Subject: the net merge-base...HEAD diff of the PR (compute it with \`${root}/review-pr/scripts/pr-context.mjs\`), read-only.`)
+    L.push('Run the four-axis adversarial scan; return schema\'d findings, each with a real `file:line`, a confidence, and a stable `theme` id.')
+    L.push(`Run \`${root}/ensure-coverage/scripts/coverage-checklist.mjs validate <checklist.md> --diff <merge-base>\` and report the result.`)
+    L.push(`Run \`${root}/review-pr/scripts/scan-diff.mjs\` and report its decidable \`findings\` channel VERBATIM — every hit is a zero-tolerance blocker.`)
+    L.push('Classify every finding `subject: code|evidence` — `evidence` only when the fix would touch no source file.')
+    if (rounds >= 1 && nonEmpty(unit.lastReviewedSha)) {
+      L.push(`Re-review (round ${rounds + 1}): \`lastReviewedSha\` is ${unit.lastReviewedSha} — scan \`${unit.lastReviewedSha}..HEAD\` with TWO dots, and reconcile every prior finding against the current tree.`)
+    } else {
+      L.push('Round 1: full scope. No `lastReviewedSha` — review the whole net diff.')
+    }
+  } else {
+    L.push('')
+    L.push('Run the close-out gates and report each one\'s output. These are the gates, with the flags that make them DECIDE rather than merely run:')
+    for (const g of PRODUCER_GATES) {
+      L.push(`  · ${root}/${g.skill}/scripts/${g.script} ${g.args}`)
+      L.push(`      ${g.why}`)
+    }
+    L.push('A gate reported without its output did not run. Re-run it.')
+    L.push('')
+    L.push('Open/update the PR with the full Review Contract, including the `Implementation Model` line (the read-back of the model you actually ran on).')
+  }
+
+  // The conditionals the leaf agent cannot compute — withheld, they downgrade the round
+  // silently rather than failing it.
+  L.push('')
+  L.push('Conditions for this round (computed by the orchestrator — do not re-derive):')
+  L.push(`  · round: ${rounds + 1}`)
+  L.push(`  · highRisk: ${unit.highRisk === true ? 'YES — apply the high-risk protocol' : 'no'}`)
+  L.push(`  · scopeClass: ${nonEmpty(unit.scopeClass) ? unit.scopeClass : 'NOT CLASSIFIED — classify at close-out and return the classifier JSON'}`)
+  if (isObject(unit.contractRevision) && nonEmpty(unit.contractRevision.sha)) {
+    L.push(`  · contractRevision: ${unit.contractRevision.sha}${Array.isArray(unit.contractRevision.refs) && unit.contractRevision.refs.length ? ` (${unit.contractRevision.refs.join(', ')})` : ''} — verify HEAD contains it and treat it as the source authority.`)
+  }
+
+  // The premise-edge invariants (2026-08-04). A unit admitted ahead of its ordering is
+  // building against something not yet true in the tree; unsaid, that is the silent
+  // false-premise failure the scheduling change traded away for this line.
+  const ordered = Array.isArray(unit.orderedAfter) ? unit.orderedAfter : []
+  if (ordered.length) {
+    L.push('')
+    L.push('You are building AHEAD of a dependency. The assumption you are building against:')
+    for (const o of ordered) {
+      L.push(`  · ${o.invariant ? `"${o.invariant}"` : '<NO INVARIANT RECORDED — do not spawn until intake records it>'}`)
+      L.push(`      ${o.unit} establishes this and has NOT landed. Design to the assumption; do not redesign around what today's tree shows. State it as its own line in the Review Contract.`)
+    }
+  }
+
+  // (b) + (c): the proof, and the channel it comes back on.
+  L.push('')
+  L.push('Return, as your final message: the PR ref, the head SHA you pushed, each gate\'s output above, the model you ran on, and anything you could not do. Deliver it as a value into this session — not a file you leave behind.')
+  L.push('─'.repeat(78))
+
+  // The renderer owns the CONTRACT — the invariant wrapper. It does not own the TASK,
+  // and the difference is easy to miss precisely because the rendered block reads as
+  // complete. That is a regression risk this file created: a hand-composed prompt always
+  // carried the work, because the author was thinking about the work; a pasted one can
+  // carry a flawless contract around an empty task. Found by an eval on 2026-08-04, where
+  // a fix contract rendered with no route for the reviewer's findings — the single most
+  // important input a fix round has, and one the manifest does not store.
+  //
+  // So the append list is part of the output, not a footnote: what state CANNOT supply,
+  // named per kind, in the same block the caller is about to paste.
+  L.push('')
+  L.push('APPEND BEFORE SENDING — state cannot supply these, and the block above is not a spawn without them:')
+  for (const a of APPENDS[kind]) L.push(`  ▸ ${a}`)
+  L.push('─'.repeat(78))
+
+  const missing = gaps(m, unit, kind)
+  // Structured env for programmatic inject (subagent_spawn env:, child process env).
+  // The text already names the same pair for paste-only orchestrators; returning the
+  // object means a launcher does not have to parse the contract text to honour clause (d).
+  // Launch id remains authoritative for guarantee 2 when the child cannot read these.
+  const env = nonEmpty(model) && !model.startsWith('<')
+    ? { [SLOT_ENV.model]: model, [SLOT_ENV.effort]: effort }
+    : null
+  return { text: L.join('\n'), gaps: missing, kind, unit: unit.id, model, effort, workspacePath: unit.workspacePath ?? null, env, slotEnvNames: { ...SLOT_ENV } }
+}

package/skills/engineering/resolve-issues/scripts/terminal-dispositions.mjs

@@ -0,0 +1,170 @@
+// One truthful terminal taxonomy for every resolve-issues lifecycle consumer.
+// Explicit dispositions are authoritative. Legacy records remain readable here.
+
+export const TERMINAL_DISPOSITIONS = ['delivered', 'handed-back', 'already-done', 'descoped', 'blocked']
+export const COMPONENT_VERDICTS = ['ALIVE', 'DEAD', 'DESCOPED']
+
+const isObject = (value) => value != null && typeof value === 'object' && !Array.isArray(value)
+const nonEmpty = (value) => typeof value === 'string' && value.trim().length > 0
+const arr = (value) => (Array.isArray(value) ? value : [])
+
+export function deliveryForUnit(unit, manifest = null) {
+  if (!isObject(unit)) return null
+  if (isObject(unit.delivery)) return unit.delivery
+  const ref = isObject(unit.deliveryRef) ? unit.deliveryRef : null
+  if (ref && nonEmpty(ref.componentId) && Number.isSafeInteger(ref.generation) && ref.generation > 0) {
+    const component = arr(manifest?.components).find((entry) => entry?.id === ref.componentId)
+    if (!component || arr(component.units).filter((id) => id === unit.id).length !== 1) return null
+    const delivery = isObject(component.delivery) ? component.delivery : null
+    if (!delivery || delivery.generation !== ref.generation) return null
+    return delivery
+  }
+  if (manifest != null) {
+    const owners = arr(manifest.components).filter((component) => isObject(component.delivery)
+      && arr(component.units).filter((id) => id === unit.id).length === 1)
+    return owners.length === 1 ? owners[0].delivery : null
+  }
+  return null
+}
+
+export function terminalDisposition(unit, manifest = null) {
+  if (!isObject(unit)) return null
+  const delivery = deliveryForUnit(unit, manifest)
+  if (TERMINAL_DISPOSITIONS.includes(unit.disposition)) {
+    const derivedRef = isObject(unit.deliveryRef) && nonEmpty(unit.deliveryRef.componentId)
+      && Number.isSafeInteger(unit.deliveryRef.generation) && unit.deliveryRef.generation > 0
+    if (unit.disposition === 'delivered') return delivery?.outcome === 'merged' && nonEmpty(delivery?.mergedSha)
+      ? 'delivered'
+      : (manifest == null && derivedRef ? 'delivered' : null)
+    if (unit.disposition === 'handed-back') return delivery?.outcome === 'handed-back' && nonEmpty(delivery?.blockedOn)
+      ? 'handed-back'
+      : (manifest == null && derivedRef ? 'handed-back' : null)
+    if (unit.disposition === 'descoped') return scopeDecisionErrors(unit.scopeDecision).length === 0 ? 'descoped' : null
+    if (unit.scopeDecision !== undefined) return null
+    return unit.disposition
+  }
+  const scopeDecision = isObject(unit.scopeDecision) ? unit.scopeDecision : null
+  if (scopeDecision && ['descope', 'descoped'].includes(scopeDecision.decision)
+      && scopeDecision.decidedBy === 'human' && scopeDecision.delivered === false) return 'descoped'
+  const outcome = delivery?.outcome ?? null
+  if (outcome === 'merged') return 'delivered'
+  if (outcome === 'handed-back') return 'handed-back'
+  if (unit.status === 'skipped-already-done') return 'already-done'
+  if (unit.status === 'blocked') return 'blocked'
+  return null
+}
+
+export function terminalDispositionTally(units, manifest = null) {
+  const tally = Object.fromEntries(TERMINAL_DISPOSITIONS.map((value) => [value, 0]))
+  const roster = arr(units).filter(isObject)
+  let unresolved = 0
+  for (const unit of roster) {
+    const disposition = terminalDisposition(unit, manifest)
+    if (disposition) tally[disposition]++
+    else unresolved++
+  }
+  return { ...tally, unresolved, total: roster.length }
+}
+
+export function scopeDecisionErrors(decision, { legacy = false } = {}) {
+  if (!isObject(decision)) return ['scopeDecision must be an object']
+  const errors = []
+  if (!['descope', 'descoped'].includes(decision.decision)) errors.push('scopeDecision.decision must be "descoped"')
+  if (decision.decidedBy !== 'human') errors.push('scopeDecision.decidedBy must be "human"')
+  if (decision.autoApplied === true) errors.push('scopeDecision refuses autoApplied:true - a descope is always a human decision')
+  if (decision.delivered !== false) errors.push('scopeDecision requires delivered:false - descope is not delivery')
+  if (!nonEmpty(decision.at)) errors.push('scopeDecision.at is required')
+  if (!nonEmpty(decision.reason)) errors.push('scopeDecision.reason is required')
+  if (!legacy) {
+    if (!nonEmpty(decision.evidence)) errors.push('scopeDecision.evidence is required human decision evidence')
+    if (!Array.isArray(decision.affectedRequirements) || !decision.affectedRequirements.length
+        || !decision.affectedRequirements.every(nonEmpty)) errors.push('scopeDecision.affectedRequirements must be a non-empty array')
+    if (!nonEmpty(decision.issueDisposition)) errors.push('scopeDecision.issueDisposition is required')
+    if (!nonEmpty(decision.prDisposition)) errors.push('scopeDecision.prDisposition is required')
+  }
+  return errors
+}
+
+export function dispositionErrors(unit, manifest = null) {
+  if (!isObject(unit)) return []
+  const errors = []
+  if (unit.disposition != null && !TERMINAL_DISPOSITIONS.includes(unit.disposition)) {
+    return [`disposition ${JSON.stringify(unit.disposition)} not in ${TERMINAL_DISPOSITIONS.join('|')}`]
+  }
+  const delivery = deliveryForUnit(unit, manifest)
+  if (unit.deliveryRef !== undefined) {
+    if (!isObject(unit.deliveryRef) || !nonEmpty(unit.deliveryRef.componentId) || !Number.isSafeInteger(unit.deliveryRef.generation) || unit.deliveryRef.generation < 1) {
+      errors.push('deliveryRef requires {componentId, generation}')
+    } else if (!delivery) errors.push('deliveryRef does not resolve to canonical component delivery')
+  }
+  if (unit.disposition === 'delivered' && delivery?.outcome !== 'merged') errors.push('disposition "delivered" requires canonical or legacy delivery.outcome "merged"')
+  if (unit.disposition === 'handed-back' && delivery?.outcome !== 'handed-back') errors.push('disposition "handed-back" requires canonical or legacy delivery.outcome "handed-back"')
+  if (unit.disposition === 'descoped') errors.push(...scopeDecisionErrors(unit.scopeDecision))
+  if (unit.scopeDecision !== undefined) {
+    errors.push(...scopeDecisionErrors(unit.scopeDecision, { legacy: unit.disposition === undefined }))
+    if (unit.disposition != null && unit.disposition !== 'descoped') errors.push(`scopeDecision conflicts with disposition ${JSON.stringify(unit.disposition)}`)
+  }
+  return [...new Set(errors)]
+}
+
+export function componentErrors(manifest) {
+  const components = manifest?.components
+  if (components === undefined) return []
+  if (!Array.isArray(components)) return ['components must be an array']
+  const units = new Map(arr(manifest?.units).filter(isObject).map((unit) => [unit.id, unit]))
+  const errors = []
+  for (const [index, component] of components.entries()) {
+    if (!isObject(component)) { errors.push(`components[${index}] must be an object`); continue }
+    if (component.verdict != null && !COMPONENT_VERDICTS.includes(component.verdict)) errors.push(`components[${index}].verdict ${JSON.stringify(component.verdict)} not in ${COMPONENT_VERDICTS.join('|')}`)
+    if (component.verdict === 'DESCOPED') {
+      for (const id of arr(component.units)) {
+        if (terminalDisposition(units.get(id), manifest) !== 'descoped') errors.push(`components[${index}] is DESCOPED but unit ${id} is not descoped`)
+      }
+    }
+  }
+  return errors
+}
+
+const dependencyId = (edge) => (typeof edge === 'string' ? edge : (isObject(edge) ? edge.unit : null))
+
+export function recordScopeDecision(manifest, unitId, payload) {
+  const errors = scopeDecisionErrors(payload)
+  if (errors.length) throw new Error(`record-scope-decision: ${errors[0]}`)
+  const out = structuredClone(manifest)
+  const units = arr(out.units)
+  const unit = units.find((entry) => entry?.id === unitId)
+  if (!unit) throw new Error(`record-scope-decision: no unit ${unitId} in this run`)
+  const existing = terminalDisposition(unit)
+  if (existing && existing !== 'blocked') throw new Error(`record-scope-decision: ${unitId} already has terminal disposition ${JSON.stringify(existing)}`)
+
+  const incoming = units.filter((candidate) => candidate?.id !== unitId
+    && arr(candidate?.dependsOn).some((edge) => dependencyId(edge) === unitId))
+  const reconciliation = arr(payload.dependencyReconciliation)
+  for (const dependent of incoming) {
+    const entry = reconciliation.find((row) => row?.unit === dependent.id)
+    if (!entry) throw new Error(`record-scope-decision: dependencyReconciliation must reconcile dependent ${dependent.id} before ${unitId} can be descoped`)
+    if (entry.action !== 'remove-edge' || !nonEmpty(entry.reason)) throw new Error(`record-scope-decision: dependencyReconciliation for ${dependent.id} requires action "remove-edge" and a reason`)
+  }
+  const unexpected = reconciliation.find((entry) => !incoming.some((dependent) => dependent.id === entry?.unit))
+  if (unexpected) throw new Error(`record-scope-decision: dependencyReconciliation names ${unexpected.unit}, which does not depend on ${unitId}`)
+  for (const dependent of incoming) dependent.dependsOn = arr(dependent.dependsOn).filter((edge) => dependencyId(edge) !== unitId)
+  unit.disposition = 'descoped'
+  unit.scopeDecision = { ...structuredClone(payload), decision: 'descoped', delivered: false }
+  return out
+}
+
+export function recordComponentVerdict(manifest, componentId, payload) {
+  if (!isObject(payload) || !COMPONENT_VERDICTS.includes(payload.verdict)) throw new Error(`record-component-verdict: verdict must be one of ${COMPONENT_VERDICTS.join('|')}`)
+  const out = structuredClone(manifest)
+  const component = arr(out.components).find((entry) => entry?.id === componentId)
+  if (!component) throw new Error(`record-component-verdict: no component ${componentId} in this run`)
+  if (component.verdict != null && component.verdict !== payload.verdict) throw new Error(`record-component-verdict: ${componentId} already has verdict ${JSON.stringify(component.verdict)}`)
+  if (payload.verdict === 'DESCOPED') {
+    const units = new Map(arr(out.units).filter(isObject).map((unit) => [unit.id, unit]))
+    const live = arr(component.units).filter((id) => terminalDisposition(units.get(id)) !== 'descoped')
+    if (live.length) throw new Error(`record-component-verdict: component ${componentId} has unit(s) not descoped: ${live.join(', ')}`)
+  }
+  component.verdict = payload.verdict
+  if (nonEmpty(payload.at)) component.verdictAt = payload.at
+  return out
+}