@1aboveio/skills 0.10.0

package/skills/engineering/resolve-issues/scripts/interference.mjs

@@ -0,0 +1,427 @@
+// interference — the scheduling primitive, and the two grades that do not have the same
+// effect (ADR 0001 decisions 1, 2, 6).
+//
+// One relation underlies both boundaries this run cares about. Two units INTERFERE when
+// one's correctness depends on the other's tree. The grades:
+//
+//   BLOCKING   the dependent cannot be CORRECTLY BUILT until the other unit is in the
+//              tree. Two sources, both blocking equally:
+//                symbol edge   the diff references symbols the other unit creates, so the
+//                              base branch does not exist yet. Fails loudly; derivable.
+//                premise edge  correctness rests on an invariant the other establishes.
+//                              Builds and passes in isolation while encoding a false
+//                              premise, so it fails SILENTLY; declarable only.
+//   ASSEMBLY   a shared surface. Each unit is green alone, the pair is red together. It
+//              prevents independent VALIDATION, not building.
+//
+// Only the blocking grade constrains scheduling. The scheduling view is a strict subset of
+// the delivery view, and `component` is the delivery view — a consequence of interference,
+// not a thing units are assigned to.
+//
+// The two sources part company at DELIVERY, which is the distinction this module exists to
+// keep. Co-delivery is owed when a unit's diff cannot stand alone in the target: either it
+// references symbols that are not there (symbol edge) or its surface is only valid in
+// combination (assembly). A premise edge leaves both intact — the diff compiles, the
+// surface is its own — and what it needs is ORDER. So a premise edge produces two
+// components with an ordering between them, not one component. The pair that forced this:
+// #553 (per-unit workspaces + the scheduler) depends on #579 (orchestrator-only manifest
+// writes) by premise, and bundling them would have co-delivered two units that share no
+// symbol and no surface.
+//
+// Vocabulary: CONTEXT.md § Interference / Scheduling. There is deliberately no term here
+// for a group of units advancing together — no wave, batch or epoch — because a run
+// refills continuously rather than at a barrier.
+
+import { terminalDisposition } from './terminal-dispositions.mjs'
+import { completionBlockers, effectiveUnitKind, unitKindComplete } from './unit-lifecycle.mjs'
+
+export const BLOCKING_SOURCES = ['symbol', 'premise']
+export { unitKindComplete }
+
+// The sources that force CO-DELIVERY. Kept as its own list rather than "everything except
+// premise": the point of the amendment is that the two grades are named by effect, and a
+// negated list would re-encode the mechanism-shaped definition that broke.
+const CO_DELIVERING_SOURCES = ['symbol']
+
+// The sources that block SCHEDULING — narrower than the ones that block delivery, and that
+// gap is the whole point (2026-08-04).
+//
+// A symbol edge blocks physically: the dependent's diff references identifiers the upstream
+// creates, so until that lands there is no tree to build against. Nothing declarative can
+// relax it.
+//
+// A premise edge does not. Its dependent compiles, its surface is its own, and what it
+// needs is ORDER — which the delivery view already enforces without any help from here:
+// `componentDependencies` below lifts EVERY cross-component edge whatever its source, and
+// `combine-and-verify.mjs mergeable` refuses "a component whose dependencies are not yet in
+// the target". So blocking the schedule too was a third enforcement of an ordering already
+// held twice, and it was the expensive one.
+//
+// What it cost, measured over 63 run manifests: runs split into two shapes with almost
+// nothing between them — declare no edges (depth 1, 10-33x parallelism) or declare a chain
+// (depth 5-19, 1.2-2.4x). `epic-25-proposal-generator` ran 12 units at 1.7x behind 18
+// premise edges while `sharedSurfaces` was 0 or 1 on every one of them; its head unit spent
+// 9 rounds and 167 minutes with eleven units queued behind an ordering assumption. Against
+// an `inFlightCap` of 4-5 a depth-7 graph can never use the slots: the floor is depth ×
+// per-unit time regardless of the cap.
+//
+// The hazard the old reading defended against — the dependent "silently encodes a false
+// premise" — survives, but silence is what makes it a hazard, and the cure for silence is
+// declaration, not serialization. Ordering the dependent LAST does not remove the premise
+// from its code; it only makes the premise true at that moment. So the edge's `invariant`
+// travels into the dependent's producer and reviewer spawns (`runnableState` returns it on
+// each `orderedAfter` entry), and the unit is built against a named assumption rather than
+// an unexamined one. The motivating incident (#553/#579, why.md § "Why the two blocking
+// sources are named by effect") was a SHIP-order failure — "parallelism on top of a live
+// lost-update race" — and nothing in it required build serialization.
+//
+// This applies the skill's own asymmetry doctrine to the grade that was exempt from it:
+// interference.md already says "an edge you are not sure about costs a serialization".
+const SCHEDULING_BLOCKING_SOURCES = ['symbol']
+
+// The in-flight cap's default. See references/why.md § the in-flight cap for the reasoning
+// and the measurement; the short version is that this bounds disk and dependency-install
+// cost, not correctness. Raised 2 → 4 (2026-07-29) on an explicit call that throughput is
+// worth more than the conservative worst case: at 4 a run with an independent roster keeps
+// four units moving instead of two, and the repo where that is a net loss pays three extra
+// installs rather than one. `inFlightCap: 1` remains the serial escape hatch.
+export const DEFAULT_IN_FLIGHT_CAP = 4
+
+const isObject = (v) => v != null && typeof v === 'object' && !Array.isArray(v)
+const nonEmpty = (v) => typeof v === 'string' && v.trim().length > 0
+const arr = (v) => (Array.isArray(v) ? v : [])
+
+// `dependsOn` entries are either a bare unit id (every manifest written before this
+// module) or `{ unit, source }`. A bare entry reads as a SYMBOL edge, which is the safe
+// interpretation in the only direction that matters: symbol co-delivers, so a legacy
+// roster keeps exactly the component shape it has today. Reading a legacy edge as a
+// premise would SPLIT a component that must merge together and ship a diff referencing
+// symbols the target does not have — a corruption, where the other error is only a cost.
+//
+// An unrecognized source takes the same fallback rather than being dropped, for the same
+// asymmetry: dropping an edge silently unblocks a unit.
+export function normalizeDependsOn(dependsOn) {
+  const out = []
+  for (const raw of arr(dependsOn)) {
+    if (nonEmpty(raw)) {
+      out.push({ unit: raw.trim(), source: 'symbol' })
+      continue
+    }
+    if (!isObject(raw) || !nonEmpty(raw.unit)) continue
+    const edge = { unit: raw.unit.trim(), source: BLOCKING_SOURCES.includes(raw.source) ? raw.source : 'symbol' }
+    // The invariant a premise edge rests on, carried through so the scheduler can hand it
+    // to the dependent's spawns. Optional and free-text: it is read by humans and by the
+    // producer contract, never branched on, so an absent one costs a less specific spawn
+    // rather than a wrong decision. Kept on symbol edges too when supplied — a symbol
+    // dependent can also rest on an invariant, it just additionally cannot compile.
+    if (nonEmpty(raw.invariant)) edge.invariant = raw.invariant.trim()
+    out.push(edge)
+  }
+  return out
+}
+
+// Every unit this one blocking-interferes with. Both sources; the grade is named by its
+// effect, so a premise edge is here exactly as a symbol edge is. This is the DELIVERY
+// view — `componentDependencies` and the merge gate read it, and both grades order there.
+export function blockingEdges(unit) {
+  return isObject(unit) ? normalizeDependsOn(unit.dependsOn) : []
+}
+
+// The subset that blocks SCHEDULING. Narrower than `blockingEdges` on purpose — see
+// SCHEDULING_BLOCKING_SOURCES above for what that gap buys and what still holds the
+// ordering it stops holding.
+export function schedulingEdges(unit) {
+  return blockingEdges(unit).filter((e) => SCHEDULING_BLOCKING_SOURCES.includes(e.source))
+}
+
+// The subset that also forces co-delivery.
+function coDeliveringEdges(unit) {
+  return blockingEdges(unit).filter((e) => CO_DELIVERING_SOURCES.includes(e.source))
+}
+
+// ---- the graph, and the one reading of "done" over it ----
+//
+// `dependencyOrder` and `isResolvedUnit` live here rather than in report.mjs because both
+// are statements about the interference graph and its units, and both now have readers on
+// either side of the reporting layer (the scheduler here; the plan/progress renders,
+// `list`'s tally and `resume`'s next-action derivation there). report.mjs re-exports them,
+// so every existing importer is unchanged — what must not happen is a second copy, because
+// two definitions of "done" let the listing say `3/5 resolved` about a run whose own
+// PROGRESS render says 2/5, and the listing is what a recovering session trusts first.
+
+export const RESOLVED = new Set(['merge-ready', 'skipped-already-done'])
+
+// Defensive about its argument on purpose: the reports that read it are the tool you reach
+// for when a run has gone wrong, which is exactly when the manifest may be hand-edited.
+//
+// This answers the LIFECYCLE question — "has this unit finished producing?" — and including
+// `merge-ready` is correct for it: `unitPushed` and `needsWorkspace` both want a yes there.
+// It is NOT the answer to "is this unit done?", which `isDoneUnit` below owns. Keeping one
+// function for both was the defect: see that comment.
+export function isResolvedUnit(unit) {
+  if (!isObject(unit)) return false
+  if (effectiveUnitKind(unit) !== 'implementation') return unitKindComplete(unit)
+  const disposition = terminalDisposition(unit)
+  return (disposition !== null && disposition !== 'blocked') || RESOLVED.has(unit.status)
+}
+
+// A `merge-ready` unit that owes a terminal delivery outcome and has none.
+//
+// `merge-ready` means the loop finished its work; it says nothing about whether the PR ever
+// reached `targetBranch`. SKILL.md is explicit that a unit with neither `merged` nor
+// `handed-back` "is reported *undelivered*, never as done" — and `handed-back` counts as
+// answered, not as a hole: it carries `blockedOn` naming the condition, so a human reading
+// the report knows what happened. The hole is *silence*.
+export function isUndeliveredUnit(unit) {
+  if (!isObject(unit)) return false
+  if (unit.status !== 'merge-ready') return false
+  if (terminalDisposition(unit) !== null) return false
+  return true
+}
+
+// The REPORTING reading of "done" — what a tally may count and a checkbox may tick.
+//
+// Why this is a second function rather than a tightening of `isResolvedUnit`: that predicate
+// has two kinds of reader with genuinely different questions, and merging them made one of
+// them wrong. The scheduler asks "is this past producing?" (merge-ready: yes). A human
+// skimming PROGRESS asks "is this finished?" (merge-ready with nothing delivered: no).
+//
+// Reproduced against epic-986's own manifest — four units `merge-ready`, `lastVerdict: PASS`,
+// PR refs recorded, `mergedSha: null` on every one — the render's headline read `4/4 units
+// resolved` with every box ticked, while the same report flagged all four UNDELIVERED one
+// line below. That incident is the reason delivery became a gated transition at all, and the
+// most-skimmed line in the report was still calling it finished. An undelivered unit is
+// *stopped*, exactly like a blocked one, and belongs beside the tally rather than inside it.
+export function isDoneUnit(unit) {
+  if (effectiveUnitKind(unit) !== 'implementation') return unitKindComplete(unit)
+  const disposition = terminalDisposition(unit)
+  return ['delivered', 'handed-back', 'already-done'].includes(disposition) || (isResolvedUnit(unit) && !isUndeliveredUnit(unit) && disposition !== 'descoped')
+}
+
+// Kahn's algorithm over the blocking edges. Returns { order, cycles }: `order` is the
+// dependency-sorted unit list SKILL.md's epic scheduling calls for, `cycles` names the
+// units left unresolvable. A cycle is reported, never thrown — it is a real thing an
+// intake can produce (two units each claiming the other as a prerequisite), and the plan
+// is the right place for the human to see it rather than a crash mid-schedule.
+//
+// BOTH sources order. A premise edge does not co-deliver, but it absolutely sequences:
+// the whole point of the grade is that the dependent silently encodes a false premise if
+// it is built first.
+export function dependencyOrder(rawUnits) {
+  const units = arr(rawUnits).filter(isObject)
+  const byId = new Map(units.map((u) => [u.id, u]))
+  const indegree = new Map(units.map((u) => [u.id, 0]))
+  const dependents = new Map(units.map((u) => [u.id, []]))
+  for (const u of units) {
+    for (const edge of blockingEdges(u)) {
+      if (!byId.has(edge.unit)) continue // dangling dep is surfaced by validation, not here
+      indegree.set(u.id, indegree.get(u.id) + 1)
+      dependents.get(edge.unit).push(u.id)
+    }
+  }
+  // Ties break on the manifest's own order so the plan is stable across renders — a
+  // roster that reshuffles between two reports is one nobody can diff.
+  const ready = units.filter((u) => indegree.get(u.id) === 0).map((u) => u.id)
+  const order = []
+  while (ready.length) {
+    const id = ready.shift()
+    order.push(byId.get(id))
+    for (const next of dependents.get(id)) {
+      indegree.set(next, indegree.get(next) - 1)
+      if (indegree.get(next) === 0) ready.push(next)
+    }
+  }
+  const cycles = units.filter((u) => !order.includes(u)).map((u) => u.id)
+  return { order, cycles }
+}
+
+// ---- runnable ----
+
+// "Pushed", not "merged". This is the whole parallelism win: today a dependent waits for
+// its dependency to be merge-ready, which serializes a chain; a dependent needs only the
+// dependency's branch to exist on the remote, which happens rounds earlier.
+//
+// Three ways to know, in descending directness. `pushedSha` is what the orchestrator
+// records when a producer pushes. A recorded PR implies a pushed branch — a PR cannot
+// exist over an unpushed head. And a resolved unit is strictly past pushing.
+export function unitPushed(unit) {
+  if (!isObject(unit)) return false
+  if (terminalDisposition(unit) === 'descoped') return false
+  if (nonEmpty(unit.pushedSha)) return true
+  if (nonEmpty(unit.pr)) return true
+  return isResolvedUnit(unit)
+}
+
+// A unit that is neither done nor parked is one the run still owes a workspace.
+function needsWorkspace(unit) {
+  if (!isObject(unit)) return false
+  if (effectiveUnitKind(unit) !== 'implementation') return false
+  if (terminalDisposition(unit) !== null || isResolvedUnit(unit)) return false
+  return unit.status !== 'blocked' && unit.status !== 'skipped-already-done'
+}
+
+// Path reserved ≠ holding (epic-867 / #945). The in-flight cap bounds disk + one dependency
+// install per unit that is actually using a tree. Pre-writing workspacePath at intake for
+// every queued unit (epic-867: all four paths recorded before any producer) used to fill
+// the cap and make admit empty even though only the foundation unit was runnable. Holding
+// requires evidence that a producer/fix has claimed the path, not merely that a path string
+// exists on a pure queued roster row.
+function holdsWorkspace(unit) {
+  if (!needsWorkspace(unit) || !nonEmpty(unit.workspacePath)) return false
+  if (unit.status === 'in-progress' || unit.status === 'merge-ready') return true
+  if (Array.isArray(unit.rounds) && unit.rounds.length > 0) return true
+  if (Number.isInteger(unit.reviewRounds) && unit.reviewRounds > 0) return true
+  if (Array.isArray(unit.reviewHistory) && unit.reviewHistory.length > 0) return true
+  if (nonEmpty(unit.pr) || nonEmpty(unit.pushedSha)) return true
+  return false
+}
+
+function coerceCap(raw) {
+  return Number.isSafeInteger(raw) && raw > 0 ? raw : DEFAULT_IN_FLIGHT_CAP
+}
+
+// The scheduling answer, as data: what is in flight, what is runnable, what may be admitted
+// now, and what each waiting unit is waiting on.
+//
+// A run advances as a continuously refilled, capped runnable set — no wave, batch or
+// barrier. Nothing here is a phase: call it whenever a unit finishes and it returns the
+// next admission. The cap counts units HOLDING a workspace, because that is the resource
+// it bounds (disk + one dependency install per unit).
+export function runnableState(manifest = {}) {
+  const m = isObject(manifest) ? manifest : {}
+  const units = arr(m.units).filter((u) => isObject(u) && nonEmpty(u.id))
+  const pendingNonImplementation = units.filter((u) => effectiveUnitKind(u) !== 'implementation' && !unitKindComplete(u))
+  const byId = new Map(units.map((u) => [u.id, u]))
+  const cap = coerceCap(m.inFlightCap)
+
+  // Dependency order, so admission never starves a dependency behind its own dependent.
+  const { order, cycles } = dependencyOrder(units)
+  const ordered = [...order, ...units.filter((u) => cycles.includes(u.id))]
+
+  const inFlight = ordered.filter((u) => holdsWorkspace(u))
+  const runnable = []
+  const waiting = []
+  for (const u of ordered) {
+    if (!needsWorkspace(u)) continue
+    // A dangling edge waits rather than passing: waiting on a unit that is not in the
+    // roster is visible and fixable, while treating it as satisfied silently bases the
+    // dependent on the wrong tree.
+    const unmet = (edges) => edges.filter((e) => !unitPushed(byId.get(e.unit)))
+    const waitingOn = unmet(schedulingEdges(u)).map((e) => e.unit)
+    // Premise edges that are not yet satisfied do NOT hold the unit back — but they are
+    // reported, because a unit admitted ahead of its ordering owes two things the caller
+    // has to act on: the invariant goes into its producer/reviewer spawns, and it must not
+    // merge first. Returning them silently as "runnable" would hand back a scheduling
+    // answer that has quietly dropped the delivery constraint it still carries.
+    const orderedAfter = unmet(blockingEdges(u))
+      .filter((e) => !SCHEDULING_BLOCKING_SOURCES.includes(e.source))
+      .map((e) => ({ unit: e.unit, source: e.source, ...(e.invariant ? { invariant: e.invariant } : {}) }))
+    if (waitingOn.length) waiting.push({ unit: u.id, waitingOn, ...(orderedAfter.length ? { orderedAfter } : {}) })
+    else {
+      const deliveryBlockedOn = completionBlockers(m, u)
+      runnable.push(orderedAfter.length || deliveryBlockedOn.length
+        ? { ...u, ...(orderedAfter.length ? { orderedAfter } : {}), ...(deliveryBlockedOn.length ? { deliveryBlockedOn } : {}) }
+        : u)
+    }
+  }
+
+  const held = new Set(inFlight.map((u) => u.id))
+  const slots = Math.max(0, cap - held.size)
+  const admit = runnable.filter((u) => !held.has(u.id)).slice(0, slots)
+
+  return { cap, inFlight, runnable, admit, waiting, cycles, pendingNonImplementation }
+}
+
+// ---- the delivery view ----
+
+// Union-find over the CO-DELIVERING relations only: symbol edges and shared surfaces. A
+// premise edge is deliberately absent — it orders, it does not bundle.
+export function deriveComponents(rawUnits) {
+  const units = arr(rawUnits).filter((u) => isObject(u) && nonEmpty(u.id))
+  const parent = new Map(units.map((u) => [u.id, u.id]))
+  const find = (id) => {
+    let root = id
+    while (parent.get(root) !== root) root = parent.get(root)
+    let walk = id
+    while (parent.get(walk) !== walk) { const next = parent.get(walk); parent.set(walk, root); walk = next }
+    return root
+  }
+  const union = (a, b) => {
+    const ra = find(a)
+    const rb = find(b)
+    if (ra !== rb) parent.set(rb, ra)
+  }
+
+  const reasons = new Map(units.map((u) => [u.id, new Set()]))
+  for (const u of units) {
+    for (const e of coDeliveringEdges(u)) {
+      if (!parent.has(e.unit)) continue // dangling; validation names it, grouping ignores it
+      union(u.id, e.unit)
+      reasons.get(u.id).add('symbol')
+      reasons.get(e.unit).add('symbol')
+    }
+  }
+  const bySurface = new Map()
+  for (const u of units) {
+    for (const s of arr(u.sharedSurfaces).filter(nonEmpty)) {
+      if (!bySurface.has(s)) bySurface.set(s, [])
+      bySurface.get(s).push(u.id)
+    }
+  }
+  for (const ids of bySurface.values()) {
+    for (let i = 1; i < ids.length; i++) {
+      union(ids[0], ids[i])
+      reasons.get(ids[0]).add('assembly')
+      reasons.get(ids[i]).add('assembly')
+    }
+  }
+
+  // Ordered by the roster's own order so the grouping is stable across renders — a
+  // component list that reshuffles between two reports is one nobody can diff.
+  const groups = new Map()
+  for (const u of units) {
+    const root = find(u.id)
+    if (!groups.has(root)) groups.set(root, [])
+    groups.get(root).push(u)
+  }
+  return [...groups.values()].map((members) => {
+    const why = new Set()
+    for (const u of members) for (const r of reasons.get(u.id)) why.add(r)
+    return {
+      // Named for its first member in roster order, so the id is stable and a human can
+      // find the component from any unit id they already have.
+      id: `component:${members[0].id}`,
+      units: members,
+      derived: true,
+      coDeliveryReasons: [...why].sort(),
+      ...(members.every((unit) => terminalDisposition(unit) === 'descoped') ? { verdict: 'DESCOPED' } : {}),
+    }
+  })
+}
+
+// The ordering a premise edge imposes, lifted to the delivery view: component → the
+// components it may not merge before. This is what `combine-and-verify.mjs mergeable`
+// consumes as its dependency-components argument, which is why the premise edge does not
+// need a bundling mechanism of its own — the merge gate already refuses a component whose
+// dependencies are not yet in the target.
+//
+// Symbol edges internal to one component vanish here (they are resolved at assembly); an
+// edge that crosses a component boundary is kept whichever source it came from, because a
+// cross-component edge is an ordering constraint either way.
+export function componentDependencies(components) {
+  const comps = arr(components).filter((c) => isObject(c) && nonEmpty(c.id))
+  const componentOf = new Map()
+  for (const c of comps) for (const u of arr(c.units)) if (nonEmpty(u?.id)) componentOf.set(u.id, c.id)
+  const out = new Map(comps.map((c) => [c.id, []]))
+  for (const c of comps) {
+    const deps = new Set()
+    for (const u of arr(c.units)) {
+      for (const e of blockingEdges(u)) {
+        const other = componentOf.get(e.unit)
+        if (other && other !== c.id) deps.add(other)
+      }
+    }
+    out.set(c.id, [...deps])
+  }
+  return out
+}

package/skills/engineering/resolve-issues/scripts/model-catalog.mjs

@@ -0,0 +1,9 @@
+// Compatibility wrapper: canonical ownership lives in harness-runtime.
+export * from '../../harness-runtime/model-catalog.mjs'
+
+import { runCli } from '../../harness-runtime/model-catalog.mjs'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+
+if (isMainModule(import.meta.url)) {
+  process.exit(runCli(process.argv.slice(2)))
+}