/gflow:live-verify — Live-verification enforcement

gflow-cli reverse-engineers a blackbox: Google Flow. Offline checks (ruff, pyright, unit/BDD tests) verify gflow-cli's own code does what it's supposed to; they cannot verify Flow still behaves the way it was captured, because Flow is external and changes without notice (see #174). This gate enforces two things, both evidence-based (no claim without a fresh verification artifact — see the superpowers:verification-before-completion skill):

1. Part 1 — Pre-flight, at the start of feature/fix work: confirm the checkout reflects current develop before investing effort.
2. Part 2 — Live-verify, before claiming done (after /code-review and /ponytail:ponytail-review, before commit/PR): exercise the change against real Flow.

Full design rationale: docs/superpowers/specs/2026-07-19-live-verify-design.md.

Part 1 — Pre-flight

Run before writing any code for a new feature/fix:

git fetch origin
git rev-parse --abbrev-ref HEAD
git rev-list --count HEAD..origin/develop
git log --oneline -5

git rev-list --count HEAD..origin/develop is an asymmetric DAG set-difference — it counts commits develop has that the current HEAD lacks, regardless of HEAD's own private unmerged history. This is what catches a genuinely diverged stale branch, not just a behind-by-fast-forward one.

• If the count is nonzero: stop. git pull (on develop) or rebase/merge (on a feature branch) before continuing.
• If the branch's last real commit looks old relative to recent develop activity (a smell for stale WIP — e.g. missing a function/guard that develop already has): stop and surface it. Don't silently proceed, don't silently switch — name the divergence and ask the user how to proceed.
• A separate sibling checkout is not itself a red flag — this project's workflow routinely uses sibling checkouts for isolated feature branches, and a real feature branch is supposed to differ from develop. The actual signal is "differs from develop in a way that suggests staleness" (missing something develop has), not "differs by adding new work on top of it." When in doubt, diff the specific file(s) about to be touched against origin/develop's version before assuming they match:

git diff origin/develop -- <path/to/file>

Part 2 — Live-verify

"Live" means: drive the real generation commands (t2i, i2i, i2v, and siblings like t2v/r2v where applicable) against a real authenticated Flow account, covering multiple variations of the change — not one happy-path call. A change touching a generation code path is default-in-scope; skipping this gate requires a named reason, not silence.

0. One plain generation, whatever changed. On a release, run gflow video t2v with nothing injected and open the file on disk. A live check of the changed feature cannot see a surface that broke on its own: Flow changed what a status reply carries, every video billed and then failed, and #1153 was found only by accident while testing a fault-injected path.

1. Define the live matrix. Before running anything, name explicitly:

• Which command(s) does the change touch?
• Which variations actually exercise it? (E.g. for a mention-resolution fix: a character mention, a media mention, an ambiguous-name case, an unresolvable name.)
• Which surface(s)? A capability that ships as both a CLI command and an MCP tool has two live paths, not one — and the MCP queued path runs different code (mcp/tools.py → queue payload → worker/codec.py → request → daemon owns download and recording). A CLI run does not exercise it. Decide per change whether the MCP path needs its own live run, and if you skip it, say so with a reason. The cheap version is usually enough: one queued MCP call on a credit-free operation proves the payload keys round-trip, which is the hop that silently no-ops (#495). Offline parity tests cannot see this — they never build a real payload and decode it.

2. Check the cost tier for each variation — the tier follows the operation, not the command family:

• Bare entity CRUD with no image generation (create_entity, list_characters, patch_entity at the API level; t2i/i2i themselves) are credit-free — run as needed to cover the matrix without a separate confirm each time. Still mind WAF/volume discipline: don't fire dozens of live calls back-to-back without surfacing it to the user first.
• Anything that generates real media is costed, even on an otherwise-free command family — e.g. gflow character create --face-prompt generates real face/body images and drives real image generation despite being "character CRUD" in name (zero credits, daily-capped); i2v and other video-generation paths are always costed. Always get explicit operator go-ahead before running a costed variation. Batch the ask: name what will run and why, once, not one confirm per call.

3. Run each variation, capture evidence per run. Use the release skill's actual 5-layer ledger shape (skills/release/SKILL.md §4b), adapted per-field to what the change under test produces:

Write this to a lightweight per-feature evidence note at tmp/live-verify/<feature-slug>.md (gitignored — this is not the full docs/LIVE_VERIFICATION_vX.Y.Z.md release ceremony). Fold it into the real LIVE_VERIFICATION doc when the feature ships in a release.

4. On pass: all matrix variations green — proceed to commit.

5. On fail: go to Failure-routing below.

Failure-routing (reproducibility re-test)

1. Check for a known match first (costed failures only, to avoid an unnecessary re-spend): grep KNOWN_ISSUES.md and open GitHub issues for a matching error signature.

gh issue list --repo ffroliva/gflow-cli --search "<error text>" --state all

2. If no match, re-test once. Free for t2i/i2i — just re-run. For a costed failure, re-testing needs the same operator confirm as any costed run.

3. Compare outcomes and route:

4. Record every outcome in the evidence note — passes, fails, and flakes are all evidence, not just the final green state.

Driver

Main context or superpowers:subagent-driven-development — never a stateless one-shot subagent. Diagnosing a live failure needs memory of what's already been tried; a fresh, context-less subagent call breaks a spike-then-fix-then-retest loop.

Pipeline Continuation (Next Step Handoff)

Upon completing Live Verification:

1. Verification 🟢 PASSED: Proactively announce: "Live verification passed. Next step: Phase 9 PR Creation & Issue Resolution (/gflow:issue-resolve <N>)."
2. Verification 🔴 FAILED: Return to Phase 6 Task Execution to resolve the identified transport failure.

Notes

• This gate does not replace /gflow:check (offline gates before commit), nor pytest -m e2e (the e2e suite against a live profile), nor /gflow:doc-review (release-time doc council) — it fills the gap between them.
• This skill is not the e2e suite, and does not satisfy the e2e-evidence rule. It drives commands by hand and writes a narrative ledger to a gitignored tmp/live-verify/ note; it never runs pytest -m e2e. A PR touching a Flow surface owes BOTH: the e2e test is the re-runnable regression, this ledger is the record of what was observed once, live. See [[e2e-evidence-is-a-contributor-deliverable]] and CONTRIBUTING § Test categories.
• Testing this skill itself means dry-running it on the next real feature that touches a generation path — there is no synthetic self-test for a live-Flow gate.