AgentHub/docs/superpowers/specs/2026-08-25-agenthub-ci-status-design.md

# `agenthub ci status` — unblock Stage 13's CI-wait half

**Status:** approved 2026-08-25.

## Problem

`ship-feature-lane`'s Stage 13 (post-merge verification) is hardcoded
skipped. Two integrations gate it: dev-CI-wait (watch CI on `development`
after a PR merges, before QCing the deployed site) and dev-QC (QC the
deployed site). Neither exists yet.

This spec covers only the CI-wait half. `agenthub lanes integration ci_wait`
already exists (`server/lib/lane-profile.js:isIntegrationEnabled`,
`bin/agenthub.js:cmdLanesIntegration`) and reports whether a profile *wants* the
integration on — but nothing acts on it. `agenthub ci` doesn't exist
(`skills/ship-feature-lane/SKILL.md:167` notes this explicitly at Stage 10,
where the skill falls back to raw `gh pr checks`/`gh run view`).

Dev-QC (QCing the deployed site) is a separate, later task — out of scope
here. Stage 13's dev-QC half stays noted as unavailable until that lands.

## Approach

**A read-only status snapshot, not a wait loop.** Per the project's
orchestration doctrine (`docs/LANES.md` § "Orchestration: what AgentHub does NOT
do" — no chaining, no queue, no retry logic), `agenthub ci status` reports a
fact once; it does not poll, block, or retry. The driving skill owns the
poll loop and the fix/escalate decision, the same shape Stage 12 already
uses for watching a PR (`sleep 300` backgrounded, re-invoked per iteration).

This also means `agenthub ci status` needs no flake classification. Stage 10
already does that triage (infra/flake signature vs. real failure) reading
`gh` output directly — Stage 13 reuses the same triage, now reading this
command's structured JSON instead of raw `gh`.

**Server-backed, following the `sync-base` pattern**, not a CLI-local `gh`
spawn. Every existing `agenthub` command is a thin HTTP client — no command in
`bin/agenthub.js` spawns a child process directly (`worktree.js`'s `git()`
helper is the only child-process boundary AgentHub has today, always
server-side). A new `server/lib/gh.js` mirrors that helper:

```js
async function gh(cwd, args) { /* execFile("gh", args, { cwd }) */ }
```

New route: `GET /api/lanes/:id/ci/status?ref=<branch-or-sha>`

- Resolves the lane's `cwd` (same lookup every other lane route uses).
- Runs `gh run list --branch <ref> --json databaseId,conclusion,status,url --limit 1`
  to find the latest run for that ref, then `gh run view <id> --json jobs`
  for per-job conclusions. (A `sha` ref: `gh run list` accepts a commit SHA
  via `--commit`, not `--branch` — the route tries `--branch` first and
  falls back to `--commit` if the ref doesn't look like a branch name a
  lane would use, i.e. it's a 7-40 char hex string.)
- No run found for the ref at all → `state: "pending"` (CI hasn't started
  yet, not an error).
- `gh` missing or not authenticated → `{ error: { message } }`, HTTP 500.

New CLI: `agenthub lanes ci status <branch-or-sha> [<lane-id>]`

- GETs the route above, prints the JSON, sets `process.exitCode`.
- Resolves the lane the same way every other `agenthub lanes <verb>` command
  does (`resolveLaneArg`), so it works with an implicit lane-from-cwd or an
  explicit id, matching `agenthub lanes integration`.

## Response shape

```json
{
  "state": "success",
  "ref": "a1b2c3d",
  "checks": [
    { "name": "server-tests", "conclusion": "failure", "url": "https://github.com/.../runs/123" }
  ]
}
```

`state` is derived, never taken from a single field: any job still
`in_progress`/`queued` → `pending`; else any `failure`/`cancelled`/
`timed_out` → `failure`; else (`success`/`skipped` only) → `success`.

## Exit codes

CLI mirrors the response into a process exit code, same convention as
`sync-base`'s distinct exit codes per outcome:

- `0` — `state: "success"`
- `1` — `state: "failure"`, OR any execution error (`gh` missing, lane not
  found, route error) — printed as `✖ ci status → <message>` on stderr
- `3` — `state: "pending"` (covers both "checks running" and "no run found
  yet for this ref")

## Skill changes

`skills/ship-feature-lane/SKILL.md` Stage 13: replace the hardcoded-skip
note with a poll loop mirroring Stage 12's:

- Get the merge SHA: `gh pr view <pr_url> --json mergeCommit -q .mergeCommit.oid`.
- Loop (`sleep 300`, `run_in_background: true`, bump heartbeat each
  iteration): `agenthub lanes ci status <sha>`.
  - `pending` → keep waiting.
  - `failure` → triage like Stage 10 (`gh run view` for job logs on the
    same run id returned in `checks[].url`), fix + re-enter from Stage 2,
    or escalate.
  - `success` → dev-QC half is still unavailable (separate task) — note
    that explicitly and proceed to Stage 14, same as today but now honest
    that CI-wait specifically passed.
- Update `docs/LANES.md`: the "Stages currently hardcoded skipped" list
  (Stage 13 becomes "CI-wait works; dev-QC still off"), the
  `agenthub lanes integration` section's claim that `ci_wait`'s consumer isn't
  built, and add `agenthub ci status` to the command reference.

## Non-goals

- No flake auto-classification or auto-rerun inside `agenthub ci status` —
  stays a dumb fact-reporter; the skill keeps owning that judgment, per
  AgentHub's no-retry-logic rule.
- No change to Stage 10 (PR CI watch) — it keeps using raw `gh` directly.
  Reusing this command there is a plausible future cleanup, not required
  now.
- No dev-QC implementation — separate task, tracked independently.

## Testing

- `server/tests` — new test for the `/api/lanes/:id/ci/status` route,
  mocking `execFile`/`gh` output for: pending (no run yet), pending
  (in-progress run), success, failure, and `gh`-not-found — pattern after
  the existing `sync-base` route tests.
- `npm run test:server` before considering this done.