@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/engineering/resolve-issues/scripts/install-hooks.mjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+// Install, or check, the compaction hook that runs rehydrate.mjs: after a context compaction the
+// coordinator is told to read its skills in full again.
+//
+//   install-hooks.mjs [--check] [--harness claude|codex] [--home <dir>] [--json] [--exit-missing]
+//
+// Writes one SessionStart entry with matcher `compact` to ~/.claude/settings.json (Claude Code)
+// and ~/.codex/hooks.json (Codex), for each harness whose home directory exists. Idempotent: an
+// entry already running rehydrate.mjs is kept, and its path updated when the skill moved. Every
+// other setting and hook is left as it was. Pi gets the same re-read from its workflow
+// extension, not from a hook file.
+//
+// --check writes nothing. Claude Code counts as installed when the engineering-workflow plugin
+// is enabled, since the plugin ships the same hook; then no settings hook is written either,
+// or the message would arrive twice.
+//
+// Exit 0 whenever it ran: each harness's status (absent, plugin, installed, updated, or
+// missing) is in the output, and --check ends with a `missing: ...` line when one lacks the hook
+// (--json prints `{ results, missing }`). Exit 2 on bad input or a settings file that is not JSON
+// (never overwritten). --exit-missing restores the old exit 1 when --check finds one missing
+// (deprecated).
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+
+export const REHYDRATE = join(dirname(fileURLToPath(import.meta.url)), 'rehydrate.mjs')
+export const PLUGIN = 'engineering-workflow@'
+const HARNESSES = {
+  claude: { dir: '.claude', file: 'settings.json' },
+  codex: { dir: '.codex', file: 'hooks.json' },
+}
+
+export class InstallHooksError extends Error {}
+
+export const hookCommand = (script = REHYDRATE) => `node "${script}" --hook`
+const isOurs = (h) => typeof h?.command === 'string' && h.command.includes('rehydrate.mjs')
+
+// The settings object with the hook in place, and whether anything changed.
+export function withHook(settings, command = hookCommand()) {
+  const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v)
+  if (!isObject(settings ?? {})) throw new InstallHooksError('the settings file is not a JSON object; fix it by hand, nothing was written')
+  const next = structuredClone(settings ?? {})
+  next.hooks ??= {}
+  next.hooks.SessionStart ??= []
+  if (!isObject(next.hooks) || !Array.isArray(next.hooks.SessionStart)) {
+    throw new InstallHooksError('hooks.SessionStart is not a list; fix it by hand, nothing was written')
+  }
+  let found = false
+  let changed = false
+  for (const group of next.hooks.SessionStart) {
+    for (const h of group?.hooks ?? []) {
+      if (!isOurs(h)) continue
+      found = true
+      if (h.command !== command) { h.command = command; changed = true }
+    }
+  }
+  if (!found) {
+    next.hooks.SessionStart.push({ matcher: 'compact', hooks: [{ type: 'command', command, timeout: 10 }] })
+    changed = true
+  }
+  return { settings: next, changed }
+}
+
+const pluginEnabled = (settings, harness) => harness === 'claude'
+  && Object.entries(settings?.enabledPlugins ?? {}).some(([k, v]) => k.startsWith(PLUGIN) && v === true)
+
+export function hasHook(settings, harness) {
+  const groups = Array.isArray(settings?.hooks?.SessionStart) ? settings.hooks.SessionStart : []
+  return groups.some((g) => (g?.hooks ?? []).some(isOurs)) || pluginEnabled(settings, harness)
+}
+
+function readJson(file) {
+  if (!existsSync(file)) return {}
+  try { return JSON.parse(readFileSync(file, 'utf8')) } catch (error) {
+    throw new InstallHooksError(`${file} is not JSON (${error.message}); fix it by hand, nothing was written`)
+  }
+}
+
+// [{ harness, file, status }] with status installed | updated | plugin | missing | absent (no
+// harness home).
+export function run({ home = homedir(), check = false, harness } = {}) {
+  const names = harness ? [harness] : Object.keys(HARNESSES)
+  const out = []
+  for (const name of names) {
+    const h = HARNESSES[name]
+    if (!h) throw new InstallHooksError(`unknown harness ${name}: use claude or codex`)
+    const file = join(home, h.dir, h.file)
+    if (!existsSync(join(home, h.dir))) { out.push({ harness: name, file, status: 'absent' }); continue }
+    const settings = readJson(file)
+    if (pluginEnabled(settings, name)) { out.push({ harness: name, file, status: 'plugin' }); continue }
+    if (check) { out.push({ harness: name, file, status: hasHook(settings, name) ? 'installed' : 'missing' }); continue }
+    const { settings: next, changed } = withHook(settings)
+    if (changed) {
+      mkdirSync(dirname(file), { recursive: true })
+      writeFileSync(`${file}.tmp`, `${JSON.stringify(next, null, 2)}\n`)
+      renameSync(`${file}.tmp`, file)
+    }
+    out.push({ harness: name, file, status: changed ? 'updated' : 'installed' })
+  }
+  return out
+}
+
+export function parseCliArgs(argv) {
+  const opts = { check: false }
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--check') { opts.check = true; continue }
+    if (argv[i] === '--json') { opts.json = true; continue }
+    if (argv[i] === '--exit-missing') { opts.exitMissing = true; continue }
+    if (['--home', '--harness'].includes(argv[i]) && argv[i + 1] !== undefined) { opts[argv[i].slice(2)] = argv[++i]; continue }
+    throw new InstallHooksError('usage: install-hooks.mjs [--check] [--harness claude|codex] [--home <dir>] [--json] [--exit-missing]')
+  }
+  return opts
+}
+
+if (isMainModule(import.meta.url)) {
+  try {
+    const opts = parseCliArgs(process.argv.slice(2))
+    const results = run(opts)
+    const missing = results.filter((r) => r.status === 'missing').map((r) => r.harness)
+    if (opts.json) process.stdout.write(`${JSON.stringify({ results, missing }, null, 2)}\n`)
+    else {
+      for (const r of results) process.stdout.write(`${r.harness.padEnd(8)}${r.status.padEnd(11)}${r.file}\n`)
+      if (missing.length) process.stdout.write(`missing: ${missing.join(', ')} (run without --check to install)\n`)
+      if (results.some((r) => r.status === 'updated')) process.stdout.write('Codex may ask you to trust the new hook at its next start.\n')
+    }
+    process.exitCode = opts.exitMissing && missing.length ? 1 : 0
+  } catch (error) {
+    process.stderr.write(`install-hooks: ${error.message}\n`)
+    process.exitCode = 2
+  }
+}

package/skills/engineering/resolve-issues/scripts/install-hooks.test.mjs

@@ -0,0 +1,79 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { spawnSync } from 'node:child_process'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { run, withHook, hookCommand, REHYDRATE } from './install-hooks.mjs'
+
+const SCRIPT = path.join(path.dirname(fileURLToPath(import.meta.url)), 'install-hooks.mjs')
+
+function home(files = {}) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'install-hooks-'))
+  for (const [rel, body] of Object.entries(files)) {
+    fs.mkdirSync(path.dirname(path.join(dir, rel)), { recursive: true })
+    fs.writeFileSync(path.join(dir, rel), typeof body === 'string' ? body : JSON.stringify(body))
+  }
+  return dir
+}
+const read = (dir, rel) => JSON.parse(fs.readFileSync(path.join(dir, rel), 'utf8'))
+
+test('installs into both harnesses, keeps every other setting and hook, and a second run changes nothing', () => {
+  const herdr = { hooks: [{ type: 'command', command: 'bash herdr.sh session' }] }
+  const dir = home({
+    '.claude/settings.json': { model: 'opus', hooks: { SessionStart: [herdr], Stop: [{ hooks: [] }] } },
+    '.codex/hooks.json': { hooks: { SessionStart: [herdr] } },
+  })
+  assert.deepEqual(run({ home: dir }).map((r) => `${r.harness}:${r.status}`), ['claude:updated', 'codex:updated'])
+  const claude = read(dir, '.claude/settings.json')
+  assert.equal(claude.model, 'opus')
+  assert.deepEqual(claude.hooks.Stop, [{ hooks: [] }])
+  assert.deepEqual(claude.hooks.SessionStart, [herdr, { matcher: 'compact', hooks: [{ type: 'command', command: hookCommand(), timeout: 10 }] }])
+  assert.deepEqual(read(dir, '.codex/hooks.json').hooks.SessionStart[1].matcher, 'compact')
+  assert.deepEqual(run({ home: dir }).map((r) => r.status), ['installed', 'installed'])
+  assert.deepEqual(run({ home: dir, check: true }).map((r) => r.status), ['installed', 'installed'])
+})
+
+test('a moved skill updates the old entry in place instead of adding a second', () => {
+  const old = { hooks: { SessionStart: [{ matcher: 'compact', hooks: [{ type: 'command', command: 'node "/old/resolve-issues/scripts/rehydrate.mjs" --hook' }] }] } }
+  const { settings, changed } = withHook(old)
+  assert.equal(changed, true)
+  assert.equal(settings.hooks.SessionStart.length, 1)
+  assert.equal(settings.hooks.SessionStart[0].hooks[0].command, `node "${REHYDRATE}" --hook`)
+})
+
+test('check: a missing hook is reported in the output (exit 0; --exit-missing exits 1) and nothing is written; an enabled plugin counts; no harness home is absent', () => {
+  const dir = home({ '.claude/settings.json': { model: 'opus' } })
+  const out = spawnSync(process.execPath, [SCRIPT, '--check', '--home', dir], { encoding: 'utf8' })
+  assert.equal(out.status, 0, out.stderr)
+  assert.match(out.stdout, /claude {2}missing/)
+  assert.match(out.stdout, /codex {3}absent/)
+  assert.match(out.stdout, /^missing: claude/m)
+  const json = JSON.parse(spawnSync(process.execPath, [SCRIPT, '--check', '--json', '--home', dir], { encoding: 'utf8' }).stdout)
+  assert.deepEqual(json.missing, ['claude'])
+  assert.equal(spawnSync(process.execPath, [SCRIPT, '--check', '--exit-missing', '--home', dir], { encoding: 'utf8' }).status, 1)
+  assert.equal(spawnSync(process.execPath, [SCRIPT, '--bogus'], { encoding: 'utf8' }).status, 2)
+  assert.deepEqual(read(dir, '.claude/settings.json'), { model: 'opus' })
+  const plugin = home({ '.claude/settings.json': { enabledPlugins: { 'engineering-workflow@1aboveio-engineering-skills': true } } })
+  assert.deepEqual(run({ home: plugin, check: true, harness: 'claude' }).map((r) => r.status), ['plugin'])
+  assert.deepEqual(run({ home: plugin, harness: 'claude' }).map((r) => r.status), ['plugin'], 'the plugin ships the hook: no second copy')
+  assert.equal(read(plugin, '.claude/settings.json').hooks, undefined)
+})
+
+test('a settings root or SessionStart of the wrong shape is refused, not silently kept', () => {
+  for (const body of [[], { hooks: { SessionStart: {} } }]) {
+    const dir = home({ '.claude/settings.json': body })
+    assert.throws(() => run({ home: dir, harness: 'claude' }), /fix it by hand/)
+    assert.deepEqual(read(dir, '.claude/settings.json'), body)
+  }
+})
+
+test('a settings file that is not JSON is never overwritten', () => {
+  const dir = home({ '.claude/settings.json': '{ "model": "opus", // comment\n}' })
+  const out = spawnSync(process.execPath, [SCRIPT, '--home', dir, '--harness', 'claude'], { encoding: 'utf8' })
+  assert.equal(out.status, 2)
+  assert.match(out.stderr, /is not JSON/)
+  assert.equal(fs.readFileSync(path.join(dir, '.claude/settings.json'), 'utf8'), '{ "model": "opus", // comment\n}')
+})

package/skills/engineering/resolve-issues/scripts/issue-tree.mjs

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+// Fetch a spec's GitHub issue tree (native sub-issues at any depth, each issue's labels and
+// native `blockedBy` links) in as few calls as possible: one GraphQL query covers three
+// levels, and follow-up queries run only where GitHub truncated something.
+//
+//   issue-tree.mjs --issue <owner/name#123> [--json]
+//
+// Exit 0 whenever it ran (an incomplete tree is `complete: false` with `errors`, not a failure);
+// 2 for a bad command.
+//
+// GraphQL caps a query at 500,000 potential nodes, counted from every `first:` multiplied
+// down the nesting, so the levels narrow (50, 20, 10 sub-issues) and each issue asks for at
+// most 20 labels and 10 blockers. A follow-up runs only for: an issue below the third
+// level that has sub-issues (re-rooted query), an issue with more sub-issues than its
+// level returned (pages of child numbers, each child re-rooted), and an issue with more
+// labels or blockers than fit (one wide detail query). Transient failures (HTTP 502/503/
+// 504, EOF, timeouts, connection resets) retry; anything still failing is listed in
+// `errors` and the tree is marked incomplete, never guessed.
+//
+// Result: { root, complete, errors, nodes: { "owner/name#n": node } } where a node is
+// { key, repo, number, title, state ('open'|'closed'), url, labels, blockedBy: [{ key, state }],
+//   children: [key] | null (null = not fetched), parent }.
+
+import { execFileSync } from 'node:child_process'
+
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+
+export const WIDTHS = [50, 20, 10]
+const LABELS = 20
+const BLOCKERS = 10
+const WIDE = 100
+const TRANSIENT = /\b(?:502|503|504)\b|EOF|ETIMEDOUT|timed? ?out|ECONNRESET|socket hang up|Bad Gateway|Service Unavailable|Gateway Timeout/i
+
+const fields = (labels, blockers) => `number title state url repository { nameWithOwner }
+  labels(first: ${labels}) { totalCount nodes { name } }
+  blockedBy(first: ${blockers}) { totalCount nodes { number state repository { nameWithOwner } } }`
+
+function level(depth) {
+  if (depth >= WIDTHS.length) return 'subIssuesSummary { total }'
+  return `subIssues(first: ${WIDTHS[depth]}) { totalCount pageInfo { hasNextPage endCursor }
+    nodes { ${fields(LABELS, BLOCKERS)} ${level(depth + 1)} } }`
+}
+
+export const TREE_QUERY = `query($owner: String!, $name: String!, $number: Int!) {
+  repository(owner: $owner, name: $name) { issue(number: $number) { ${fields(LABELS, BLOCKERS)} ${level(0)} } } }`
+
+export const PAGE_QUERY = `query($owner: String!, $name: String!, $number: Int!, $after: String!) {
+  repository(owner: $owner, name: $name) { issue(number: $number) {
+    subIssues(first: ${WIDE}, after: $after) { pageInfo { hasNextPage endCursor } nodes { number repository { nameWithOwner } } } } } }`
+
+export const DETAIL_QUERY = `query($owner: String!, $name: String!, $number: Int!) {
+  repository(owner: $owner, name: $name) { issue(number: $number) { ${fields(WIDE, WIDE)} } } }`
+
+export const keyOf = (repo, number) => `${repo}#${number}`
+const split = (key) => { const i = key.lastIndexOf('#'); return { repo: key.slice(0, i), number: Number(key.slice(i + 1)) } }
+
+// Retry a call while it fails transiently; `sleep` is injected so tests do not wait.
+export function withRetry(fn, { attempts = 3, sleep = sleepSync } = {}) {
+  return (...args) => {
+    for (let i = 1; ; i++) {
+      try { return fn(...args) } catch (error) {
+        if (i >= attempts || !TRANSIENT.test(String(error?.message || error))) throw error
+        sleep(1000 * i)
+      }
+    }
+  }
+}
+
+function sleepSync(ms) { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms) }
+
+// `graphql(query, variables)` returns the response's `data`; inject it to test without GitHub.
+export function fetchTree(rootRef, { graphql = ghGraphql, attempts = 3, sleep } = {}) {
+  const call = withRetry(graphql, { attempts, sleep })
+  const nodes = {}
+  const errors = []
+  const root = keyOf(rootRef.repo, rootRef.number)
+  const issueOf = (key, query, extra = {}) => {
+    const { repo, number } = split(key)
+    const [owner, name] = repo.split('/')
+    const issue = call(query, { owner, name, number, ...extra })?.repository?.issue
+    if (!issue) throw new Error(`issue ${key} not found`)
+    return issue
+  }
+  const followUps = []
+
+  // Record an issue and everything nested under it; queue follow-ups for what was cut off.
+  const record = (raw, parent) => {
+    const repo = raw.repository?.nameWithOwner
+    const key = keyOf(repo, raw.number)
+    const prior = nodes[key]
+    const node = {
+      key, repo, number: raw.number, title: raw.title ?? null,
+      state: String(raw.state || '').toLowerCase(), url: raw.url ?? null,
+      labels: (raw.labels?.nodes ?? []).map((l) => l.name),
+      blockedBy: (raw.blockedBy?.nodes ?? []).map((b) => ({ key: keyOf(b.repository?.nameWithOwner ?? repo, b.number), state: String(b.state || '').toLowerCase() })),
+      children: null,
+      parent: prior?.parent ?? parent,
+    }
+    nodes[key] = node
+    if ((raw.labels?.totalCount ?? 0) > node.labels.length || (raw.blockedBy?.totalCount ?? 0) > node.blockedBy.length) followUps.push({ kind: 'detail', key })
+    if (raw.subIssues) {
+      node.children = raw.subIssues.nodes.map((child) => record(child, key))
+      if (raw.subIssues.pageInfo?.hasNextPage) followUps.push({ kind: 'page', key, after: raw.subIssues.pageInfo.endCursor })
+    } else if ((raw.subIssuesSummary?.total ?? 0) === 0) {
+      node.children = []
+    } else {
+      followUps.push({ kind: 'reroot', key })
+    }
+    return key
+  }
+
+  try {
+    record(issueOf(root, TREE_QUERY), null)
+  } catch (error) {
+    return { root, complete: false, errors: [{ key: root, error: String(error?.message || error) }], nodes }
+  }
+  while (followUps.length) {
+    const job = followUps.shift()
+    try {
+      if (job.kind === 'reroot') record(issueOf(job.key, TREE_QUERY), nodes[job.key]?.parent ?? null)
+      else if (job.kind === 'detail') {
+        const raw = issueOf(job.key, DETAIL_QUERY)
+        const node = nodes[job.key]
+        node.labels = (raw.labels?.nodes ?? []).map((l) => l.name)
+        node.blockedBy = (raw.blockedBy?.nodes ?? []).map((b) => ({ key: keyOf(b.repository?.nameWithOwner ?? node.repo, b.number), state: String(b.state || '').toLowerCase() }))
+      } else if (job.kind === 'page') {
+        const page = issueOf(job.key, PAGE_QUERY, { after: job.after }).subIssues
+        for (const child of page.nodes) {
+          const childKey = keyOf(child.repository?.nameWithOwner, child.number)
+          nodes[job.key].children.push(childKey)
+          nodes[childKey] = { key: childKey, parent: job.key }
+          followUps.push({ kind: 'reroot', key: childKey })
+        }
+        if (page.pageInfo?.hasNextPage) followUps.push({ kind: 'page', key: job.key, after: page.pageInfo.endCursor })
+      }
+    } catch (error) {
+      errors.push({ key: job.key, error: String(error?.message || error) })
+    }
+  }
+  return { root, complete: errors.length === 0, errors, nodes }
+}
+
+export function ghGraphql(query, variables) {
+  const args = ['api', 'graphql', '-f', `query=${query}`]
+  for (const [name, value] of Object.entries(variables)) args.push(typeof value === 'number' ? '-F' : '-f', `${name}=${value}`)
+  const out = JSON.parse(execFileSync('gh', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 60_000 }))
+  if (out.errors?.length) throw new Error(out.errors.map((e) => e.message).join('; '))
+  return out.data
+}
+
+if (isMainModule(import.meta.url)) {
+  const i = process.argv.indexOf('--issue')
+  const m = /^([^/\s#]+\/[^/\s#]+)#(\d+)$/.exec(process.argv[i + 1] ?? '')
+  if (i < 0 || !m) {
+    console.error('usage: issue-tree.mjs --issue <owner/name#123>')
+    process.exitCode = 2
+  } else {
+    const tree = fetchTree({ repo: m[1], number: Number(m[2]) })
+    console.log(JSON.stringify(tree, null, 2))
+    // exit 0 whenever it ran: `complete` and `errors` in the output say whether the tree is whole
+  }
+}

package/skills/engineering/resolve-issues/scripts/issue-tree.test.mjs

@@ -0,0 +1,107 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { DETAIL_QUERY, PAGE_QUERY, TREE_QUERY, WIDTHS, fetchTree, withRetry } from './issue-tree.mjs'
+
+// A fake GitHub GraphQL endpoint over issues keyed "o/r#n": { state, labels, blockedBy, children }.
+// It honors the query's level widths, so truncation and follow-ups behave as on GitHub.
+function fakeGraphql(issues, { fail = {} } = {}) {
+  const calls = []
+  const node = (key, depth, widths) => {
+    const i = issues[key]
+    const [repo, n] = key.split('#')
+    const labels = i.labels ?? []
+    const blockers = i.blockedBy ?? []
+    const out = {
+      number: Number(n), title: `t${n}`, state: (i.state ?? 'open').toUpperCase(), url: null, repository: { nameWithOwner: repo },
+      labels: { totalCount: labels.length, nodes: labels.slice(0, widths.labels).map((name) => ({ name })) },
+      blockedBy: { totalCount: blockers.length, nodes: blockers.slice(0, widths.blockers).map((b) => ({ number: Number(b.split('#')[1]), state: (issues[b]?.state ?? 'open').toUpperCase(), repository: { nameWithOwner: b.split('#')[0] } })) },
+    }
+    const kids = i.children ?? []
+    if (depth >= WIDTHS.length) out.subIssuesSummary = { total: kids.length }
+    else {
+      const shown = kids.slice(0, WIDTHS[depth])
+      out.subIssues = { totalCount: kids.length, pageInfo: { hasNextPage: kids.length > shown.length, endCursor: String(shown.length) }, nodes: shown.map((k) => node(k, depth + 1, widths)) }
+    }
+    return out
+  }
+  const graphql = (query, { owner, name, number, after }) => {
+    const key = `${owner}/${name}#${number}`
+    const kind = query === TREE_QUERY ? 'tree' : query === DETAIL_QUERY ? 'detail' : query === PAGE_QUERY ? 'page' : 'unknown'
+    calls.push(`${kind} ${key}`)
+    if (fail[key]) { const err = fail[key]; if (typeof err === 'number') { fail[key]--; throw new Error('HTTP 502 Bad Gateway') } throw new Error(err) }
+    if (!issues[key]) return { repository: { issue: null } }
+    if (kind === 'tree') return { repository: { issue: node(key, 0, { labels: 20, blockers: 10 }) } }
+    if (kind === 'detail') { const full = node(key, WIDTHS.length, { labels: 100, blockers: 100 }); delete full.subIssuesSummary; return { repository: { issue: full } } }
+    const kids = issues[key].children.slice(Number(after), Number(after) + 100)
+    return { repository: { issue: { subIssues: { pageInfo: { hasNextPage: Number(after) + 100 < issues[key].children.length, endCursor: String(Number(after) + 100) }, nodes: kids.map((k) => ({ number: Number(k.split('#')[1]), repository: { nameWithOwner: k.split('#')[0] } })) } } } }
+  }
+  return { graphql, calls }
+}
+const noSleep = () => {}
+
+test('one query fetches three levels with labels and blockers', () => {
+  const { graphql, calls } = fakeGraphql({
+    'o/r#1': { children: ['o/r#2', 'o/r#3'] },
+    'o/r#2': { state: 'closed', labels: ['ready-for-agent'] },
+    'o/r#3': { children: ['x/y#4'], blockedBy: ['o/r#2'] },
+    'x/y#4': { labels: ['ready-for-agent'] },
+  })
+  const tree = fetchTree({ repo: 'o/r', number: 1 }, { graphql, sleep: noSleep })
+  assert.equal(tree.complete, true)
+  assert.deepEqual(calls, ['tree o/r#1'])
+  assert.deepEqual(tree.nodes['o/r#3'].children, ['x/y#4'])
+  assert.deepEqual(tree.nodes['o/r#3'].blockedBy, [{ key: 'o/r#2', state: 'closed' }])
+  assert.equal(tree.nodes['x/y#4'].parent, 'o/r#3')
+  assert.equal(tree.nodes['o/r#2'].state, 'closed')
+})
+
+test('follow-ups run only where GitHub truncated: depth, child pages, wide labels or blockers', () => {
+  const many = Array.from({ length: 55 }, (_, i) => `o/r#${100 + i}`)
+  const issues = {
+    'o/r#1': { children: ['o/r#2', ...many] },
+    'o/r#2': { children: ['o/r#3'], blockedBy: Array.from({ length: 12 }, (_, i) => `o/r#${200 + i}`) },
+    'o/r#3': { children: ['o/r#4'] },
+    'o/r#4': { children: ['o/r#5'] },
+    'o/r#5': {},
+  }
+  for (const k of many) issues[k] = {}
+  const { graphql, calls } = fakeGraphql(issues)
+  const tree = fetchTree({ repo: 'o/r', number: 1 }, { graphql, sleep: noSleep })
+  assert.equal(tree.complete, true)
+  assert.equal(tree.nodes['o/r#1'].children.length, 56, 'every child, past the first level width')
+  assert.deepEqual(tree.nodes['o/r#4'].children, ['o/r#5'], 'the fourth level came from a re-rooted query')
+  assert.equal(tree.nodes['o/r#5'].parent, 'o/r#4')
+  assert.equal(tree.nodes['o/r#2'].blockedBy.length, 12, 'a wide detail query filled the blockers')
+  const pagedChildren = many.slice(49).map((k) => `tree ${k}`)
+  assert.deepEqual([...calls].sort(), ['tree o/r#1', 'detail o/r#2', 'tree o/r#4', 'page o/r#1', ...pagedChildren].sort(), 'one follow-up per truncation, nothing else')
+})
+
+test('transient failures retry; a lasting failure marks the tree incomplete', () => {
+  const issues = { 'o/r#1': { children: ['o/r#2'] }, 'o/r#2': {} }
+  const flaky = fakeGraphql(issues, { fail: { 'o/r#1': 2 } })
+  assert.equal(fetchTree({ repo: 'o/r', number: 1 }, { graphql: flaky.graphql, sleep: noSleep }).complete, true)
+  assert.equal(flaky.calls.length, 3)
+  const down = fakeGraphql(issues, { fail: { 'o/r#1': 5 } })
+  const tree = fetchTree({ repo: 'o/r', number: 1 }, { graphql: down.graphql, sleep: noSleep })
+  assert.equal(tree.complete, false)
+  assert.match(tree.errors[0].error, /502/)
+  const denied = fakeGraphql(issues, { fail: { 'o/r#1': 'Could not resolve to a Repository' } })
+  fetchTree({ repo: 'o/r', number: 1 }, { graphql: denied.graphql, sleep: noSleep })
+  assert.equal(denied.calls.length, 1, 'a non-transient error is not retried')
+})
+
+test('withRetry gives up after its attempts', () => {
+  let n = 0
+  const call = withRetry(() => { n++; throw new Error('read: EOF') }, { attempts: 3, sleep: noSleep })
+  assert.throws(call, /EOF/)
+  assert.equal(n, 3)
+})
+
+test('the tree query stays under GitHub’s 500,000-node limit', () => {
+  // GitHub multiplies `first:` down the nesting; each issue also asks for 20 labels and 10 blockers.
+  let issues = 1
+  let total = 0
+  for (const width of WIDTHS) { issues *= width; total += issues * (1 + 20 + 10) }
+  assert.ok(total < 500_000, `estimated ${total} nodes`)
+})

package/skills/engineering/resolve-issues/scripts/manual-invocation.test.mjs

@@ -0,0 +1,14 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { manualOnlyPolicyFindings } from '../../engineering-runtime/scripts/invocation-policy.mjs'
+
+const engineeringRoot = resolve(dirname(fileURLToPath(import.meta.url)), '../..')
+
+test('issue and release orchestrators require explicit invocation', () => {
+  for (const name of ['resolve-issues', 'rush-issues', 'rush-release', 'resolve-release']) {
+    assert.deepEqual(manualOnlyPolicyFindings(resolve(engineeringRoot, name)), [], name)
+  }
+})

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

@@ -0,0 +1,9 @@
+// Thin 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)))
+}