gstack/landing-report/SKILL.md.tmpl

---
name: landing-report
version: 0.1.0
description: |
  Read-only queue dashboard for workspace-aware ship. Shows which VERSION slots
  are currently claimed by open PRs, which sibling Conductor workspaces have
  WIP work likely to ship soon, and what slot /ship would pick next. No
  mutations — just a snapshot. Use when asked to "landing report", "what's in
  the queue", "show me open PRs", or "which version do I claim next". (gstack)
triggers:
  - landing report
  - version queue
  - ship queue
  - what version comes next
  - show open PR versions
allowed-tools:
  - Bash
  - Read
sensitive: false
---

# /landing-report — Version Queue Dashboard

{{PREAMBLE}}

---

## Why this skill exists

When you're running 5-10 parallel Conductor workspaces, it helps to see — at a
glance — which version numbers are claimed, by whom, and what slot your next
`/ship` would land in. This skill is a read-only call into the same
`bin/gstack-next-version` utility `/ship` uses, but with nothing mutating.
Think of it as `gh pr list` for VERSION numbers.

---

## Step 1: Detect platform and base branch

Same detection as other gstack skills.

```bash
BASE_BRANCH=$(gh pr view --json baseRefName -q .baseRefName 2>/dev/null || \
              gh repo view --json defaultBranchRef -q .defaultBranchRef.name 2>/dev/null || \
              echo main)
echo "Base branch: $BASE_BRANCH"
```

---

## Step 2: Read current state

```bash
CURRENT_VERSION=$(cat VERSION 2>/dev/null | tr -d '[:space:]' || echo "0.0.0.0")
git fetch origin "$BASE_BRANCH" --quiet 2>/dev/null || true
BASE_VERSION=$(git show "origin/$BASE_BRANCH:VERSION" 2>/dev/null | tr -d '[:space:]' || echo "$CURRENT_VERSION")
echo "origin/$BASE_BRANCH VERSION: $BASE_VERSION"
echo "branch HEAD VERSION: $CURRENT_VERSION"
```

---

## Step 3: Query the queue

Call the util three times — once for each bump level — so the user sees what
they'd claim for micro/patch/minor/major. Cheap (same gh call cached by bun).

```bash
for LEVEL in micro patch minor major; do
  bun run bin/gstack-next-version \
    --base "$BASE_BRANCH" \
    --bump "$LEVEL" \
    --current-version "$BASE_VERSION" \
    > "/tmp/landing-$LEVEL.json" 2>/dev/null || echo '{"offline":true}' > "/tmp/landing-$LEVEL.json"
done
```

---

## Step 4: Render the dashboard

Build a single table output. Use the `patch`-level JSON as canonical for
queue + siblings (they're identical across bump levels; only `.version`
differs).

Use `jq` to extract:
- `.host` — github | gitlab | unknown
- `.offline` — did the query fail?
- `.claimed` — array of {pr, branch, version, url}
- `.siblings` — all sibling worktrees found
- `.active_siblings` — subset that's likely about to ship

Render in this exact format:

```
╔══════════════════════════════════════════════════════════════════╗
║                     GSTACK LANDING REPORT                        ║
╠══════════════════════════════════════════════════════════════════╣
║ Repo:    <owner/repo>                                            ║
║ Base:    <base> @ v<base-version>                                ║
║ Host:    <github|gitlab|unknown>                                 ║
║ Status:  <ONLINE|OFFLINE: queue-awareness unavailable>           ║
╚══════════════════════════════════════════════════════════════════╝

Open PRs claiming versions on <base>:
  #1152  alpha-branch         → v1.7.0.0
  #1153  beta-branch          → v1.7.0.0  ⚠ collision with #1152
  #1151  gamma-branch         → v1.6.5.0

Sibling Conductor worktrees (<workspace_root>):
  path                        branch                 VERSION      last commit   PR
  ──────────────────────────────────────────────────────────────────────────────────
  ../tokyo-v2                 feat/dashboard         v1.7.1.0    3h ago         none  ★ active
  ../melbourne                feat/review            v1.6.0.0    12d ago        none
  ../osaka                    feat/payments          v1.8.0.0    5h ago         #1155

★ active = has VERSION ahead of base AND last commit < 24h AND no open PR.
  These are the ones likely to ship soon.

If you ran /ship right now, you'd claim:
  micro bump:  v1.6.3.1   (queue-advance: none)
  patch bump:  v1.7.1.0   (bumped past claimed 1.7.0.0)
  minor bump:  v1.8.0.0   (bumped past claimed 1.7.0.0)
  major bump:  v2.0.0.0   (no major collisions)
```

For offline / unknown-host output, print a shorter block:

```
╔══════════════════════════════════════════════════════════════════╗
║                     GSTACK LANDING REPORT                        ║
╠══════════════════════════════════════════════════════════════════╣
║ Status:  OFFLINE — queue-awareness unavailable                   ║
║ Reason:  <offline reason from warnings>                          ║
╚══════════════════════════════════════════════════════════════════╝

Fallback: local VERSION bumps still work, but collisions cannot be detected.
```

---

## Step 5: Suggest next action

After rendering the table, suggest ONE of:

1. **If there are collisions in the queue** (two open PRs claim the same version):
   "⚠ Two open PRs collide on v<X>. Whoever merges second will either overwrite
   the first's CHANGELOG entry or land a duplicate. Consider asking one author
   to rerun /ship to pick up the next free slot."

2. **If an active sibling outranks the user's branch version:**
   "Sibling worktree <path> has v<X> committed <N>h ago and hasn't PR'd yet.
   If that work ships first, your branch will need to rebump at land time."

3. **If everything looks clean:**
   "Queue is clean. Next /ship will claim a slot without conflict."

---

## Plan Mode

PLAN MODE EXCEPTION — ALWAYS RUN. This skill is entirely read-only: no file
writes, no git mutations, no network state changes. Safe to run in plan mode.