# Project Bluefin — Reviewer Guide

> Machine-readable briefing for human and AI reviewers.  
> Canonical URL: **https://queue.projectbluefin.io/review-guide.md**  
> Dashboard: **https://queue.projectbluefin.io/**

---

## What You Are Reviewing

`projectbluefin` is an **agentic-first OS factory**. AI agents implement the majority of PRs; humans provide design approval, security review, and merge authorization. Your job as a reviewer is not to verify that every line was written by a human — it is to catch the things machines reliably miss.

Full context: **https://docs.projectbluefin.io/agentic-contributing**

---

## The Dashboard

**https://queue.projectbluefin.io/** — the Clanker Control Panel — is a live view of everything waiting for a human decision across the `projectbluefin` org.

| Section | What it shows |
|---|---|
| Stats bar | P0 blockers · P1 this-cycle · Triage · Open issues · PRs ready · Velocity since cycle start |
| ✔ Approved | PRs with all required approvals — ready to merge now |
| ⏳ Review required | CI passing, needs one or more additional approvals |
| ○ No review yet | CI passing, nobody has looked yet |
| 🔴 P0 / 🟡 P1 | Hive-tracked blockers and cycle items (right column, top) |
| 🤖 Agent Ready Queue | Org-wide issues labeled `queue/agent-ready` — ready for agent pickup (right column, below P0/P1) |

Each PR card shows the **approval count** prominently. The dashboard auto-refreshes every 5 minutes without a page reload.

**Data file** (machine-readable): `https://queue.projectbluefin.io/data.json`  
This JSON is regenerated every 10 minutes by GitHub Actions and contains the complete current state — PR lists, review counts, issue tiers, and velocity counts. Agents can `curl` this URL to get a structured snapshot without scraping the HTML.

---

## Merge Rules

### `projectbluefin/common` (most PRs land here)

| Rule | Value |
|---|---|
| Required approvals | **2** |
| Required status check | `Build and push image` |
| Smoke tests | Non-blocking — stale failures from prior runs do not block merge |
| Renovate bypass | Yes — Renovate PRs auto-merge without the review requirement |

One approval → PR stays in `review:required` (yellow tier).  
Two approvals → PR moves to `review:approved` (green tier) and is safe to merge.

### `projectbluefin/bluefin` and `projectbluefin/bluefin-lts`

Same 2-approval ruleset. Promotion from `testing` to `stable/lts` requires a separate 2-human Environment gate in `weekly-testing-promotion.yml`.

### `projectbluefin/dakota`

1-approval minimum. BuildStream builds are slower; CI run time is 20–40 min.

### `projectbluefin/actions`

1-approval minimum. Changes here propagate to all image repos — treat with extra care.

---

## What To Check When Reviewing

### Always check

- [ ] **Does the PR do what it says?** Read the title and description. If the description is missing or vague, that is itself a problem.
- [ ] **Does CI pass?** The dashboard only shows PRs with `status:success` — if a PR is here, CI is green.
- [ ] **Review count** — shown prominently on each card. If it shows 1, one more approval gets it to green.

### For agent PRs

- [ ] **Skill file update** — agent PRs should include a `.github/skills/` update in the same PR. A PR touching CI, build, or packaging without a skill update is a yellow flag. The hive skill-drift check will post an advisory; your job is to decide if the omission is justified.
- [ ] **Scope** — did the agent stay in scope? Agents sometimes over-reach. If the diff is significantly larger than the issue description, read carefully.
- [ ] **Security gate** — any PR touching auth, signing, supply chain, secrets handling, or COPR/third-party sources **must stop** for explicit human approval before merge. Do not merge these on a single review.
- [ ] **Design gate** — architecture changes and new subsystems should have been proposed as a draft PR or issue first. If you see a large structural change with no prior proposal, ask.

### For human PRs

Same checks, plus: human PRs often lack the structured commit format agents use. That is fine. Focus on correctness and scope.

---

## Human Gates — When to Slow Down

Agents implement autonomously **except** at these four gates. If you see a PR that touches one, apply extra scrutiny:

| Gate | Trigger | Required action |
|---|---|---|
| **Design Gate** | Architecture changes, new subsystem design, behavior changes visible to users | Confirm a proposal existed and was approved before implementation |
| **Security Gate** | Auth, signing, supply chain, secrets handling, COPR/third-party sources | Do not merge on one review. Two maintainer eyes minimum. |
| **User Impact Gate** | Regressions, breaking changes, removals that affect end users | Verify a `ujust report` issue or explicit user request exists |
| **Promotion Gate** | `testing` → `stable` or `testing` → `lts` promotion | Requires 2-human Environment gate in GitHub Actions |

---

## Hive Labels

| Label | Meaning | Dashboard location |
|---|---|---|
| `hive/p0` | Release blocker — fix before anything else this cycle | Red P0 column (right) |
| `hive/p1` | Must land this cycle | Yellow P1 column (right) |
| `needs-triage` | Needs a human to categorize | Triage tier (below main grid) |
| `queue/agent-ready` | Ready for agent pickup | Agent Ready Queue (right column, below P0/P1) |
| `queue/claimed` | Agent has claimed this | Not shown on dashboard |
| `agent/blocked` | Agent is blocked, needs human input | Blocked tier (below main grid) |

`hive/` labels are dynamic — reset each cycle by the hive formation. `priority/p0` etc. are static repo-level labels. Both can coexist on the same issue.

---

## Repos Tracked

| Repo | Role |
|---|---|
| [projectbluefin/bluefin](https://github.com/projectbluefin/bluefin) | Main OS image (Fedora-based) |
| [projectbluefin/bluefin-lts](https://github.com/projectbluefin/bluefin-lts) | LTS variant (CentOS Stream 10 / bootc) |
| [projectbluefin/common](https://github.com/projectbluefin/common) | Shared OCI layer — desktop config, ujust, GNOME opinions |
| [projectbluefin/dakota](https://github.com/projectbluefin/dakota) | Distroless prototype (BuildStream) |
| [projectbluefin/actions](https://github.com/projectbluefin/actions) | Shared CI library |
| [projectbluefin/renovate-config](https://github.com/projectbluefin/renovate-config) | Renovate dependency update config |
| [projectbluefin/bonedigger](https://github.com/projectbluefin/bonedigger) | Client + issue lifecycle bot |
| [projectbluefin/knuckle](https://github.com/projectbluefin/knuckle) | Homelab / k3s layer |

---

## Quick Reference

```bash
# Check live hive status (no auth required)
~/src/hive-status

# P0 blockers across the org
gh search issues --label "hive/p0" --owner projectbluefin --state open

# P1 this-cycle
gh search issues --label "hive/p1" --owner projectbluefin --state open

# Agent-ready issues across the org
gh search issues --label "queue/agent-ready" --owner projectbluefin --state open

# Everything waiting for review
gh search prs --owner projectbluefin --state open --review required

# Machine-readable dashboard snapshot
curl https://queue.projectbluefin.io/data.json | jq '.prs.required | length'

# Agent-ready count from data snapshot
curl https://queue.projectbluefin.io/data.json | jq '.issues.agentReady | length'
```

---

## Further Reading

| Resource | URL |
|---|---|
| Agentic Contributor Guide | https://docs.projectbluefin.io/agentic-contributing |
| Legacy Contributor Guide | https://docs.projectbluefin.io/contributing |
| THEPATTERN.md | https://github.com/projectbluefin/bluefin/blob/main/THEPATTERN.md |
| KubeStellar Hive (live) | https://kubestellar.io/live/hive/bluefin/ |
| Common skills index | https://github.com/projectbluefin/common/blob/main/docs/skills/INDEX.md |
| Queue source | https://github.com/projectbluefin/queue |