@1aboveio/skills 0.10.0

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

@@ -0,0 +1,494 @@
+// The run's two standing reports: the PLAN (post-intake, before the first producer
+// spawn) and PROGRESS (after each unit reaches a terminal state).
+//
+// Why these are rendered from the manifest rather than written in prose. The skill
+// already mandates every fact in them — the decomposition gate's deferrals, the
+// dependency-sorted roster, the component grouping, the risk flags, the units blocked on
+// a design input. What it did not have was a moment where they are all said out loud at
+// once, so they were reported when the run was short and attentive and quietly skipped
+// when it was long — which is exactly when the human has lost track. A renderer reports
+// the same fields every time, and reports them from the state the gates actually wrote,
+// so a plan cannot claim a unit is scheduled that the manifest never recorded.
+//
+// The honesty rule this file exists to keep: **a report never invents what the manifest
+// does not hold.** Where a field is missing it says so (`— not recorded`) rather than
+// omitting the line, because a silently-short plan reads as a complete one. That is the
+// epic-848 shape at the reporting layer: the requirement nobody owned was invisible
+// precisely because nothing ever listed what was unowned.
+
+import { gateAudit } from './fix-rounds.mjs'
+import { componentRoundProfile } from './component-candidate.mjs'
+import { deliveryForUnit, terminalDisposition, terminalDispositionTally } from './terminal-dispositions.mjs'
+import {
+  blockingEdges, deriveComponents, dependencyOrder, isDoneUnit, isResolvedUnit, isUndeliveredUnit, RESOLVED,
+} from './interference.mjs'
+import { effectiveUnitKind, unitKindComplete } from './unit-lifecycle.mjs'
+
+// The interference graph's primitives moved to `interference.mjs`, where the scheduler
+// reads them too. Re-exported here — unchanged, one definition — so every existing
+// importer (`run-state.mjs`, this skill's tests) keeps its import path.
+export { dependencyOrder, isDoneUnit, isResolvedUnit, isUndeliveredUnit, RESOLVED }
+
+const isObject = (v) => v != null && typeof v === 'object' && !Array.isArray(v)
+// Every list read from the manifest is filtered to real objects, and every sha is
+// stringified before slicing. These reports are the tool you reach for when a run has gone
+// wrong — which is exactly when the manifest may be hand-edited or half-written — so a
+// renderer that throws on a malformed field fails at the only moment it is needed. The CLI
+// write paths refuse these shapes, but nothing stops a human from opening the JSON.
+const nonEmpty = (v) => typeof v === 'string' && v.trim().length > 0
+const arr = (v) => (Array.isArray(v) ? v : [])
+const objs = (v) => arr(v).filter(isObject)
+const sha7 = (v) => (nonEmpty(v) ? v.slice(0, 7) : String(v ?? ''))
+
+// ---- what still owes the human an answer before the loop can start ----
+
+// Collected rather than counted: the plan's job is to name each one, since "2 blocked"
+// tells the human nothing they can act on.
+export function openAsks(manifest) {
+  const asks = []
+  for (const u of objs(manifest.units)) {
+    if (terminalDisposition(u) === 'blocked') {
+      asks.push({ unit: u.id, ask: nonEmpty(u.blocker) ? u.blocker : 'blocked — no reason recorded (record it in units[].blocker)' })
+    }
+    const b = isObject(u.breaker) ? u.breaker : null
+    // A decided-but-not-re-entered design/split/descope blocks every transition until
+    // intake re-entry, so it is an open ask even though the decision was made.
+    if (b && b.decision && b.decision !== 'continue' && !b.reenteredAt) {
+      asks.push({ unit: u.id, ask: `circuit-breaker decided "${b.decision}" — blocked until the unit re-enters intake (record-intake-reentry)` })
+    }
+  }
+  for (const d of objs(manifest.decisions)) {
+    if (d?.status === 'pending-human') asks.push({ unit: '—', ask: `open decision: ${d.question}` })
+  }
+  return asks
+}
+
+// ---- shared framing ----
+
+function header(manifest) {
+  const m = manifest
+  const models = isObject(m.models) ? m.models : {}
+  const eff = (slot) => (nonEmpty(models[`${slot}Effort`]) ? ` @ ${models[`${slot}Effort`]}` : ' @ high')
+  const subject = nonEmpty(m.epic) ? `epic ${m.epic}` : `run ${m.slug ?? ''}`.trim()
+  const lines = [
+    `${subject} → ${m.targetBranch ?? '(no target branch recorded)'}`,
+    `  delivery: ${m.deliveryMode ?? 'direct (legacy default — probe it at pre-flight)'}`
+      + `   merge-shippable: ${m.mergeShippable ? 'ON' : 'off (hand back merge-ready)'}`
+      + `   breaker: ${m.breakerAutonomy ?? 'auto'}`,
+    // The pre-flight autonomy level is what the human actually answered; merge-shippable
+    // above is one of the knobs it sets. Rendering only the knob left the human unable to
+    // see, in the one report they read before any code is built, how much of the loop's
+    // stop-and-ask surface they had pre-authorized.
+    `  autonomy: ${m.autonomy ?? 'supervised (not set — every park stops and asks)'}`
+      // The trigger belongs beside merge-shippable, not buried in the manifest: on an
+      // auto-merge repo the two together decide whether a routine review merges the PR,
+      // and that is a fact the human should see in the plan rather than discover.
+      + `   enqueue: ${m.enqueueTrigger ?? 'trigger not probed'}${m.enqueueTrigger && m.enqueueTrigger !== 'manual' && !m.mergeShippable ? ' ⚠ auto-merge + merge-shippable off — reviews post as comments' : ''}`
+      + `   workspace: ${m.workspaceMode ?? 'shared'}`,
+    `  implementer: ${models.implementation ?? '— not recorded'}${models.implementation ? eff('implementation') : ''}`
+      + `   reviewer: ${models.review ?? '— not recorded'}${models.review ? eff('review') : ''}`,
+  ]
+  if (models.implementation && models.implementation === models.review) {
+    lines.push('  ** reviewer === implementer — the review is NOT independent (guarantee 2) **')
+  }
+  return lines
+}
+
+// Group units by component. When the manifest records components those win — they carry
+// the delivery state (`pr`, `verdict`, `mergedSha`) nothing can re-derive. When it records
+// none, the grouping is DERIVED from interference rather than flattened into one bag,
+// because `component` is interference's delivery view and a report that shows one blob is
+// a report that cannot say which units must merge together.
+//
+// The derivation is where the two blocking sources part company, and getting it wrong is
+// the bug ADR 0001's amendment names: a SYMBOL edge co-delivers (the dependent's diff
+// references symbols only the other unit has), a PREMISE edge only ORDERS. Treating every
+// `dependsOn` edge as co-delivery would have bundled #553 with #579 — two units that share
+// no symbol and no surface.
+//
+// A unit in no component is still listed — an omitted unit is the failure this whole
+// report exists to prevent.
+function groups(manifest, ordered) {
+  const components = objs(manifest.components)
+  if (!components.length) {
+    return deriveComponents(ordered).map((c) => ({ id: c.id, units: c.units, derived: true, coDeliveryReasons: c.coDeliveryReasons }))
+  }
+  const claimed = new Set()
+  const out = components.map((c) => {
+    const ids = new Set(arr(c.units))
+    const units = ordered.filter((u) => ids.has(u.id))
+    units.forEach((u) => claimed.add(u.id))
+    return { id: c.id, pr: c.pr, verdict: c.verdict, mergedSha: c.delivery?.mergedSha ?? c.mergedSha, delivery: c.delivery, candidate: c.candidate, authorizationBoundary: c.authorizationBoundary, units }
+  })
+  const orphans = ordered.filter((u) => !claimed.has(u.id))
+  if (orphans.length) out.push({ id: '(no component)', units: orphans })
+  return out
+}
+
+// The roster reads as a task list, because that is the question a human actually brings
+// to it — "what is done, what is left" — and a checkbox answers it before any of the tags
+// are read. Deliberately only the two GitHub-renderable markers: these reports get pasted
+// into PR bodies and handoffs, and `- [!]` for blocked would render as literal text there.
+// Blocked stays visible where it already was, in the status word and the tally line, which
+// counts it BESIDE the resolved figure rather than inside it.
+//
+// `isDoneUnit` is the same rule PROGRESS's tally uses — one reading of "done" across the
+// reporting surfaces, so a checkbox can never disagree with the count above it. It is
+// deliberately NOT `isResolvedUnit`: that one answers the scheduler's question and says yes
+// to a `merge-ready` unit that never delivered, which is how every box came up ticked on
+// epic-986's four undelivered units.
+const checkbox = (u) => (['delivered', 'handed-back', 'already-done'].includes(terminalDisposition(u)) ? '- [x] ' : '- [ ] ')
+
+const riskTag = (u) => (u.highRisk ? 'HIGH-RISK' : 'routine')
+
+// The scope class (#515), rendered BESIDE the risk tag rather than folded into it —
+// they are two axes and the whole point is that they are independent: `highRisk`
+// decides how deep the review goes, `scopeClass` decides which coverage/evidence
+// artifacts apply. A `no-surface` unit is routinely high-risk (`.mergify.yml`, CI
+// workflows, IAM bindings), and a reader who sees one tag must not infer the other.
+//
+// An unclassified unit prints `scope:—` rather than nothing, per this file's honesty
+// rule: "not classified yet" and "classified surface-bearing" are different states,
+// and only the first is still owed work. Silence would make them look alike.
+const scopeTag = (u) => ` · scope:${nonEmpty(u.scopeClass) ? u.scopeClass : '—'}`
+const kindTag = (u) => ` · kind:${effectiveUnitKind(u)}`
+const tags = (u) => `[${riskTag(u)}${scopeTag(u)}${kindTag(u)}]`
+
+// Both blocking sources are rendered, and they are rendered DIFFERENTLY, because they tell
+// the reader different things about the same roster. A symbol edge says "this ships with
+// that"; a premise edge says "this ships after that" — and a premise edge is the one that
+// exists nowhere else, since it can only be declared, never derived from a diff. Printing
+// them alike is what made the distinction invisible in the first place.
+function stacksOn(u) {
+  const edges = blockingEdges(u)
+  if (!edges.length) return ''
+  const symbol = edges.filter((e) => e.source === 'symbol').map((e) => e.unit)
+  const premise = edges.filter((e) => e.source === 'premise').map((e) => e.unit)
+  const parts = []
+  if (symbol.length) parts.push(`← stacks on ${symbol.join(', ')}`)
+  if (premise.length) parts.push(`← after ${premise.join(', ')} (premise)`)
+  return `  ${parts.join('  ')}`
+}
+
+// ---- the PLAN: what the loop is about to do ----
+
+export function renderPlan(manifest) {
+  const units = objs(manifest.units)
+  const { order, cycles } = dependencyOrder(units)
+  const ordered = [...order, ...units.filter((u) => cycles.includes(u.id))]
+  const out = ['PLAN', ...header(manifest), '']
+
+  if (!units.length) {
+    out.push('  no units — intake has not normalized the input into a roster yet')
+    return out.join('\n')
+  }
+
+  const comps = groups(manifest, ordered)
+  const plural = (n, s) => `${n} ${s}${n === 1 ? '' : 's'}`
+  out.push(`  ${plural(units.length, 'unit')} in ${plural(comps.length, 'component')}, dependency-sorted:`)
+  for (const c of comps) {
+    // A derived component says WHY it co-delivers, because that is the fact a reader has
+    // no other way to check: `component:#879 (ships together — symbol)` is falsifiable
+    // against the roster, while an unexplained grouping is something to take on trust.
+    const why = arr(c.coDeliveryReasons).length ? ` — ${arr(c.coDeliveryReasons).join(' + ')}` : ''
+    out.push(c.id ? `    ${c.id}${c.units.length > 1 ? ` (ships together${why})` : ''}` : '    (single component)')
+    for (const u of c.units) {
+      const contract = isObject(u.contractRevision) && nonEmpty(u.contractRevision.sha)
+        ? `contract ${sha7(u.contractRevision.sha)}`
+        : 'no contract pointer'
+      out.push(`      ${checkbox(u)}${u.id}  ${u.status ?? 'queued'}  ${tags(u)}  ${contract}${stacksOn(u)}`)
+    }
+  }
+
+  // The decomposition gate's output. Rendered even when empty, because "nothing was
+  // deferred" and "nobody ran the gate" look identical if the section is omitted — and
+  // telling those apart is the whole point of epic-848.
+  out.push('')
+  const deferrals = arr(manifest.deferrals)
+  if (deferrals.length) {
+    out.push('  deferred — tracked, NOT built by this run:')
+    for (const d of deferrals) out.push(`    ${d.requirement} → ${d.trackedIn ?? '** no tracking issue — this requirement is owned by nobody **'}`)
+  } else if (nonEmpty(manifest.epic)) {
+    out.push('  deferred: none recorded — if the decomposition gate found unowned parent requirements, record them (deferrals[]) before spawning')
+  }
+
+  if (cycles.length) {
+    out.push('', `  ** dependency cycle among ${cycles.join(', ')} — these cannot be scheduled until it is broken **`)
+  }
+
+  // Outside the open-asks branch: the graph is a property of the roster, not of whether
+  // anything happens to be blocked. Nesting it there rendered it only on runs that already
+  // had a problem — the opposite of a plan's job, which is to show the shape before one.
+  out.push(...graphSection(manifest))
+
+  const asks = openAsks(manifest)
+  if (asks.length) {
+    out.push('', `  ${plural(asks.length, 'item')} need${asks.length === 1 ? 's' : ''} you before these units can move:`)
+    for (const a of asks) out.push(`    ${a.unit}  ${a.ask}`)
+  }
+  return out.join('\n')
+}
+
+// ---- PROGRESS: what has actually happened ----
+
+// Two different questions the word "terminal" was doing double duty for, and conflating
+// them let a blocked unit read as progress:
+//   - WHEN to report  — a unit stopped moving, blocked included. That is the cadence.
+//   - What counts as RESOLVED — the unit is done. A blocked unit is stopped, not done,
+//     and folding it into the tally would inflate the number with the units that most
+//     need attention.
+// So `blocked` triggers a report but is counted separately, on the same line, where it
+// stays visible instead of either padding the numerator or vanishing from the summary.
+// `RESOLVED` and `isResolvedUnit` are the ONE reading of "done", and they now live in
+// `interference.mjs` (re-exported at the top of this file) because the scheduler asks the
+// same question this render does. Four readers share it — PROGRESS's tally below,
+// `run-state.mjs list`'s per-run tally, `resume`'s next-action derivation, and the
+// runnable set — and a textually-copied rule is a rule that drifts one reader at a time,
+// with the drifted copy being whichever one a recovering session happens to trust.
+
+export function renderProgress(manifest, options = {}) {
+  const units = objs(manifest.units)
+  const { order, cycles } = dependencyOrder(units)
+  const ordered = [...order, ...units.filter((u) => cycles.includes(u.id))]
+  const out = ['PROGRESS', ...header(manifest), '']
+
+  if (!units.length) return [...out, '  no units'].join('\n')
+
+  const tally = terminalDispositionTally(ordered, manifest)
+  const undelivered = ordered.filter(isUndeliveredUnit)
+  // Undelivered sits beside the tally for the same reason blocked does: it is a unit that
+  // STOPPED, not one that finished. Naming it on the headline is the point — the per-unit
+  // UNDELIVERED flag was already there on epic-986 and the `4/4 units resolved` above it
+  // is what got read.
+  const aside = [
+    undelivered.length ? `${undelivered.length} undelivered` : (tally.unresolved ? `${tally.unresolved} unresolved` : null),
+  ].filter(Boolean)
+  const dispositionSummary = [
+    `${tally.delivered} delivered`,
+    tally['handed-back'] ? `${tally['handed-back']} handed back` : null,
+    tally['already-done'] ? `${tally['already-done']} already done` : null,
+    tally.descoped ? `${tally.descoped} human-descoped` : null,
+    tally.blocked ? `${tally.blocked} blocked` : null,
+  ].filter(Boolean).join(' · ')
+  const resolved = tally.delivered + tally['handed-back'] + tally['already-done']
+  out.push(`  ${dispositionSummary}` + (aside.length ? `   ${aside.join(', ')}, waiting on you` : ''))
+  out.push(`  ${resolved}/${units.length} units resolved (descopes excluded)`)
+  const implementations = ordered.filter((u) => effectiveUnitKind(u) === 'implementation')
+  const deliveredImplementations = implementations.filter((u) => terminalDisposition(u) === 'delivered')
+  const external = ordered.filter((u) => effectiveUnitKind(u) === 'external-verification')
+  const externalComplete = external.filter(unitKindComplete)
+  if (implementations.length) out.push(`  code delivery: ${deliveredImplementations.length}/${implementations.length} implementation units delivered`)
+  if (external.length) out.push(`  external verification: ${externalComplete.length}/${external.length} complete, ${external.length - externalComplete.length} pending`)
+  out.push('')
+
+  for (const c of groups(manifest, ordered)) {
+    // A DERIVED single-unit component is not a fact about the run — it is this renderer
+    // restating the unit it is about to print, one line up, plus an integration verdict that
+    // will never exist because there is nothing to integrate. On a single-unit run that was
+    // the majority of the output. Declared components always print (the human named them,
+    // and their verdict/mergedSha are real), as does any derived group that actually
+    // combines units, which is where an integration verdict means something.
+    const worthPrinting = c.id && (!c.derived || c.units.length > 1)
+    if (worthPrinting) {
+      const v = c.verdict ? `  integration: ${c.verdict}` : '  integration: not yet run'
+      const candidate = isObject(c.candidate) ? c.candidate : null
+      const profile = candidate ? componentRoundProfile(c) : null
+      const candidateState = candidate
+        ? `  candidate:${candidate.state}@g${candidate.generation} ${sha7(candidate.frozen?.headSha ?? candidate.updates?.at(-1)?.headSha)}`
+        : ''
+      const rounds = profile
+        ? `  component rounds discovery:${profile.unitDiscovery} fix:${profile.integrationFix} terminal:${profile.terminalAuthorization}`
+        : ''
+      out.push(`    ${c.id}${v}${candidateState}${rounds}${c.mergedSha ? `  merged ${sha7(c.mergedSha)}` : ''}`)
+    }
+    for (const u of c.units) {
+      const rounds = arr(u.rounds).length || u.reviewRounds || 0
+      const verdict = u.lastVerdict ?? '—'
+      // Delivery is the part most likely to be silently in-flight: epic-986 reported four
+      // units merge-ready with mergedSha null on every one. Say it plainly.
+      let delivery = ''
+      const unitKind = effectiveUnitKind(u)
+      if (unitKind === 'external-verification') {
+        delivery = unitKindComplete(u)
+          ? `  EXTERNAL VERIFICATION COMPLETE via ${u.externalProtocol?.completionSource ?? '(no source)'}`
+          : '  ** PENDING EXTERNAL VERIFICATION — artifacts do not satisfy this criterion **'
+      } else if (unitKind === 'human-decision') {
+        delivery = unitKindComplete(u) ? '  HUMAN DECISION RECORDED' : '  ** PENDING HUMAN DECISION **'
+      } else if (unitKind === 'prerequisite') {
+        delivery = unitKindComplete(u) ? '  PREREQUISITE COMPLETE' : '  ** PENDING PREREQUISITE **'
+      } else {
+        const disposition = terminalDisposition(u, manifest)
+        const evidence = deliveryForUnit(u, manifest)
+        if (disposition === 'delivered') delivery = `  DELIVERED ${evidence?.mergedSha ? sha7(evidence.mergedSha) : '(no sha!)'}`
+        else if (disposition === 'handed-back') delivery = `  handed back: ${evidence?.blockedOn ?? '(no reason recorded)'}`
+        else if (disposition === 'already-done') delivery = '  ALREADY DONE (prior art)'
+        else if (disposition === 'descoped') delivery = `  HUMAN-DESCOPED: ${u.scopeDecision?.reason ?? '(no reason recorded)'}`
+        else if (disposition === 'blocked') delivery = `  BLOCKED: ${u.blocker ?? '(no reason recorded)'}`
+        else if (u.status === 'merge-ready') delivery = '  ** UNDELIVERED — merge-ready with no terminal outcome **'
+      }
+      const breaker = isObject(u.breaker)
+        ? `  breaker:${u.breaker.decision}${u.breaker.autoApplied ? '(auto)' : ''}`
+        : ''
+      out.push(`      ${checkbox(u)}${u.id}  ${u.status ?? 'queued'}  ${tags(u)}  ${rounds} round${rounds === 1 ? '' : 's'}, last ${verdict}${breaker}${delivery}`)
+    }
+  }
+
+  // This run's gate-value snapshot. `gate-audit` adds the durable cross-run window used for
+  // retirement; progress stays run-local so reading status does not create observations.
+  // Printed even when empty: "no gate results recorded" is the finding, and omitting the
+  // section would hide exactly what the removal path asks for.
+  const gates = options.gateValue ?? gateAudit(manifest)
+  const seen = gates.filter((g) => !g.unrecorded)
+  out.push(...graphSection(manifest))
+  out.push('', '  gates:')
+  if (!seen.length) {
+    out.push('    none recorded — a gate that passed and a gate that never ran are indistinguishable in this run')
+  } else {
+    for (const g of seen) {
+      const bits = [`ran ${g.ran}`]
+      if (g.states?.ranClean) bits.push(`clean ${g.states.ranClean}`)
+      if (g.skipped) bits.push(`skipped ${g.skipped}`)
+      if (g.states?.notRun) bits.push(`not run ${g.states.notRun}`)
+      if (g.states?.unreadable) bits.push(`unreadable ${g.states.unreadable}`)
+      if (g.findings) bits.push(`${g.findings} raw finding${g.findings === 1 ? '' : 's'}`)
+      if (g.uniqueFindings) bits.push(`${g.uniqueFindings} unique`)
+      if (g.blockingFindings) bits.push(`${g.blockingFindings} blocking`)
+      if (g.repeatedKnownWarnings) bits.push(`${g.repeatedKnownWarnings} repeated`)
+      if (g.fixesAttributed) bits.push(`${g.fixesAttributed} fixed`)
+      if (g.noiseFindings) bits.push(`${g.noiseFindings} noise`)
+      if (g.failed) bits.push(`${g.failed} rejection${g.failed === 1 ? '' : 's'}`)
+      out.push(`    ${g.gate.padEnd(19)} ${bits.join(', ')}`
+        + (g.recommendations?.retirement ? '   ** durable zero-yield window — retirement review **' : '')
+        + (g.recommendations?.deduplication ? '   ** deduplicate repeated findings **' : '')
+        + (g.recommendations?.narrowing ? '   ** consider narrowing **' : ''))
+    }
+    const silent = gates.filter((g) => g.unrecorded).map((g) => g.gate)
+    if (silent.length) out.push(`    not recorded at all: ${silent.join(', ')}`)
+  }
+
+  const asks = openAsks(manifest)
+  if (asks.length) {
+    out.push('', `  waiting on you:`)
+    for (const a of asks) out.push(`    ${a.unit}  ${a.ask}`)
+  }
+  return out.join('\n')
+}
+
+// ---- the dependency graph ----
+//
+// The roster already renders dependency-SORTED with per-unit `← stacks on` annotations, and
+// that is enough to answer "what does this one unit wait for". It is not enough to answer
+// the questions a human actually opens a checkpoint report to ask on an epic: what can move
+// right now, what is the critical chain, and which single unit is holding up the most work.
+// Those are properties of the whole graph, and a sorted list flattens them away — a unit at
+// the bottom of the list looks the same whether it waits on one finished thing or on a chain
+// of four that have not started.
+//
+// How many units transitively wait on this one — the "unblocks N" figure. A unit blocking a
+// long chain is where attention pays off, and that ranking is invisible in a sorted list.
+export function blockedDownstream(units, id) {
+  const list = objs(units)
+  const seen = new Set()
+  let frontier = [id]
+  while (frontier.length) {
+    const next = []
+    for (const u of list) {
+      if (seen.has(u.id) || u.id === id) continue
+      if (blockingEdges(u).some((e) => frontier.includes(e.unit))) { seen.add(u.id); next.push(u.id) }
+    }
+    frontier = next
+  }
+  return seen.size
+}
+
+const count = (n, s) => `${n} ${s}${n === 1 ? '' : 's'}`
+
+// Plain glyphs, deliberately NOT `- [x]`/`- [ ]`. The roster's checkboxes are GitHub task-list
+// syntax (see the checkbox comment above); reusing that syntax here would make every graph row
+// render as a separate, tickable task in a PR body. These are status marks inside a picture.
+const GLYPH = (u) => (isDoneUnit(u) ? '✓' : isUndeliveredUnit(u) || ['blocked', 'descoped'].includes(terminalDisposition(u)) ? '!' : '·')
+
+// Appended to PLAN and PROGRESS, and only when the roster actually has edges. A run with no
+// dependencies gains nothing from a graph header saying so — the same noise rule that removed
+// the derived single-unit component lines. `graphSection` returns [] there, so the caller can
+// splat it unconditionally and the report simply does not grow a section it cannot fill.
+export function graphSection(manifest) {
+  const g = renderGraph(manifest)
+  return g ? ['', g] : []
+}
+
+export function renderGraph(manifest) {
+  const units = dependencyOrder(objs(manifest.units)).order
+  const all = objs(manifest.units)
+  const ordered = [...units, ...all.filter((u) => !units.includes(u))]
+  if (!ordered.some((u) => blockingEdges(u).length)) return ''
+  return textGraph(ordered)
+}
+
+function textGraph(ordered) {
+  const byId = new Map(ordered.map((u) => [u.id, u]))
+  const kids = new Map(ordered.map((u) => [u.id, []]))
+  for (const u of ordered) {
+    for (const e of blockingEdges(u)) {
+      if (kids.has(e.unit)) kids.get(e.unit).push({ id: u.id, source: e.source })
+    }
+  }
+  const roots = ordered.filter((u) => !blockingEdges(u).some((e) => byId.has(e.unit)))
+
+  // A DAG drawn as a tree has to do something about a node with two parents. Dropping the
+  // second edge is the thing that hides why a unit is stuck, so instead the node appears under
+  // EVERY parent and each appearance after the first is marked as a cross-link and not
+  // expanded again. That keeps the picture a tree to read while staying a DAG in fact — and
+  // the `seen` set is also what makes a cycle terminate rather than recurse forever.
+  const seen = new Set()
+  const out = ['  dependency graph    ├── ships WITH (symbol)    ├┈┈ ships AFTER (premise)', '']
+
+  const label = (u) => {
+    const held = blockedDownstream(ordered, u.id)
+    const holds = held && !isDoneUnit(u) ? `   holds ${count(held, 'unit')}` : ''
+    // A DANGLING edge — `dependsOn` naming a unit no longer (or never) on the roster — has to
+    // be drawn, not dropped. It cannot be drawn as a connector because there is no node to
+    // connect to, so without this the unit renders as a root with no blockers: visually
+    // identical to a genuinely unblocked unit, while `runnableState` refuses to admit it and
+    // reports it waiting. Two answers to "can this move now" is the disagreement this codebase
+    // keeps paying for, and here the chart was the one that read as safe. The scheduler's rule
+    // is the right one and this now matches it: a dangling edge is visible and fixable, where
+    // treating it as satisfied would silently base the dependent on the wrong tree.
+    const dangling = blockingEdges(u).filter((e) => !byId.has(e.unit)).map((e) => e.unit)
+    const missing = dangling.length ? `   ** waits on ${dangling.join(', ')} — not in the roster **` : ''
+    return `${GLYPH(u)} ${u.id.padEnd(7)} ${(u.status ?? 'queued').padEnd(12)}${holds}${missing}`
+  }
+
+  const walk = (unit, prefix) => {
+    const children = kids.get(unit.id) ?? []
+    children.forEach((c, i) => {
+      const last = i === children.length - 1
+      const elbow = last ? '└' : '├'
+      const line = c.source === 'premise' ? '┈┈' : '──'
+      const child = byId.get(c.id)
+      if (seen.has(c.id)) {
+        const parents = blockingEdges(child).map((e) => e.unit).filter((x) => x !== unit.id)
+        out.push(`${prefix}${elbow}${line} ${GLYPH(child)} ${child.id}   ↑ shown above — also waits on ${parents.join(', ')}`)
+        return
+      }
+      seen.add(c.id)
+      out.push(`${prefix}${elbow}${line} ${label(child)}`)
+      walk(child, `${prefix}${last ? '    ' : '│   '}`)
+    })
+  }
+
+  for (const r of roots) {
+    seen.add(r.id)
+    out.push(`  ${label(r)}`)
+    walk(r, '  ')
+  }
+  // Anything a cycle left unreachable from a root still prints — an omitted unit is the
+  // failure this whole report exists to prevent.
+  for (const u of ordered) {
+    if (!seen.has(u.id)) out.push(`  ${label(u)}   ** unreachable — dependency cycle **`)
+  }
+  // Trailing spaces come from the column padding and would show up as diff noise the moment
+  // this report is pasted into a PR body.
+  return out.map((l) => l.replace(/\s+$/, '')).join('\n')
+}
+