gh-advance

Move an issue forward through its lifecycle, enforcing the gate.

What it does

1. Read target issue: mcp__github__issue_read({issue_number})
2. Determine current status from labels (the unique status:* label)
3. Determine target status:
   • If user specifies one ("move to in-testing"), use it
   • Otherwise advance to the natural next status per workflow:
     • in-progress → ready-for-testing (Gate 1)
     • in-testing → ready-for-docs (Gate 2)
     • in-docs → documented (Gate 3, auto-skipped for bug/hotfix/testcase — go straight to documented with placeholder comment)
     • documented → in-review (Gate 4, requires PR)
     • in-review → done (Gate 5, requires user approval)
4. Look up the gate for from → to in workflows/default.yaml
5. If free transition: update via the unified setter (updates Project Status field + status:* label):
   bash
   Done.
6. Branch-policy pre-check (Gate 1 only): per workflows/default.yaml#branching.gate1_refuses_protected_base, before validating Gate 1 evidence, check the current git branch. If it is in branching.protected_base (default: main / master) AND the issue's kind is in branching.pr_required_kinds, REJECT:
   text
   Skip this check only if the issue body or a comment contains the literal string [gh-pms: branch-exception] (a one-off escape hatch — should be rare).
7. If gated: a. Check cooldown: read ~/.cache/gh-pms/state.json[issue_key].last_transition_at. If < 30s ago, REJECT: Gate cooldown: last transition was {N}s ago. Wait {30-N}s and verify your evidence is real, not boilerplate. b. Build the evidence comment from the user's input. The user provides evidence either inline or as a structured payload. Format MUST be:
   markdown
   c. Run lib/validate-evidence.sh (via Bash tool) — passes evidence + gate spec, returns { valid: bool, errors: [...] } d. If invalid, STOP and report each error:
   text
   e. If valid:
   • Post the evidence as a comment via mcp__github__add_issue_comment
   • Update via unified setter (label + Project Status field):
     bash
   • Update ~/.cache/gh-pms/state.json[issue_key].last_transition_at = now()
   • Update current_status = to
   • Report:
     text
8. For Gate 4 (documented → in-review): must verify a PR is open with Closes #{N} in body. Use mcp__github__list_pull_requests to find any PR mentioning the issue number. If no PR exists, route the user to /gh-pms:gh-push #{N} which handles push + PR creation + review-request in one shot. Then run the CI check:
   bash
   • Exit 0 → Gate 4 proceeds.
   • Exit 1 → REFUSE the transition. The script prints which checks are failing/pending and the override hint.
   • Override: if the user passes --ignore-checks "<reason>", skip the refusal but append a ## Check overrides section to the gate evidence comment with the reason. This is for cases like "flaky linter, will fix in follow-up #123" — the audit trail is the point. Don't let it become a habit; the cooldown won't help here.
9. For Gate 5 (in-review → done): this skill REJECTS direct calls. User must approve via /gh-pms:gh-review's submit_review step. Return: Cannot advance to status:done directly. Use /gh-pms:gh-review to request user approval, then submit the decision.

Auto-skip logic for kinds

Per workflows/default.yaml gates[*].skip_for_kinds:

• bug, hotfix, testcase → skip Gate 3 (docs)
• When skipping: insert a system comment Gate 3 auto-skipped (kind: bug) and proceed ready-for-docs → documented in one move.

Programmatic guardrails (re-state)

• Cooldown: 30s between transitions
• WIP limit: enforced by gh-current not here (advance assumes you're already current)
• Evidence file-path check: ## Changes and ## Checklist must contain at least one path that exists in the repo (- prefix list, validate via Bash test -f)
• Branch-policy check (Gate 1): refuses to advance feature work that is still on the protected base branch — see step 6 above
• macOS bash 3.2 compatibility: lib/validate-evidence.sh uses bash 4+ associative arrays. On systems with only bash 3 (default on macOS), the validator errors with declare: -A: invalid option. Until the script is rewritten, fall back to a manual section-length + file-existence check before posting evidence; this is a known plugin issue tracked separately.

Cross-skill contract

After Gate 4 passes, the agent calls AskUserQuestion to ask: "Approve PR #X / Closes #N?" with options Approve / Needs Edits. Then runs /gh-pms:gh-review with the decision.