gflow-cli 0.51.0__tar.gz → 0.52.0__tar.gz

{gflow_cli-0.51.0 → gflow_cli-0.52.0}/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gflow",
-  "version": "0.51.0",
+  "version": "0.52.0",
   "description": "Reusable development and operations workflows for gflow-cli",
   "author": {
     "name": "Flavio Oliva",

{gflow_cli-0.51.0 → gflow_cli-0.52.0}/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.52.0] — 2026-08-05
+
+### Added
+
+- **Intra-batch reference support for image batches (#317).** `BatchPromptItem` and `gflow image batch` now support `ref` and `reference_entity` fields (e.g. `ref="batch:0"`), with topological dependency sorting and circular dependency validation.
+- **Character entity provenance recording and video CLI flag parity (#402).** Added `--reference-entity` and `--reference-entity-name` CLI options to `gflow video` commands (`t2v`, `i2v`, `r2v`) and verified character provenance recording in `operations.metadata_json`.
+
+### Fixed
+
+- **Fix video duration selector drift (#451).** Expanded duration control selector cascade to match modern Flow editor UI elements (`button`, `role='button'`, `role='option'`, `role='menuitem'`, `role='tab'`) while preserving fail-closed behavior on missing duration controls.
+
+
+
+
+
 ## [0.51.0] — 2026-08-05
 
 ### Security
@@ -2728,7 +2743,8 @@ shell-script template that branches on these codes.
 
 First skeleton. Not functional end-to-end yet.
 
-[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.51.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.52.0...HEAD
+[0.52.0]: https://github.com/ffroliva/gflow-cli/compare/v0.51.0...v0.52.0
 [0.51.0]: https://github.com/ffroliva/gflow-cli/compare/v0.50.0...v0.51.0
 [0.50.0]: https://github.com/ffroliva/gflow-cli/compare/v0.49.0...v0.50.0
 [0.49.0]: https://github.com/ffroliva/gflow-cli/compare/v0.48.0...v0.49.0

{gflow_cli-0.51.0 → gflow_cli-0.52.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.51.0
+Version: 0.52.0
 Summary: Unofficial CLI for Google Flow — drive Veo image-to-video generations from the terminal.
 Project-URL: Homepage, https://github.com/ffroliva/gflow-cli
 Project-URL: Issues, https://github.com/ffroliva/gflow-cli/issues

{gflow_cli-0.51.0 → gflow_cli-0.52.0}/docs/INDEX.md

@@ -135,7 +135,7 @@ Slash commands for Claude Code, stored in `.claude/commands/gflow/`. All prefixe
 **"A command failed — where is the incident bundle and what's in it?"** → [DEBUGGING § Automatic incident bundles](DEBUGGING.md#automatic-incident-bundles) (layout, triggers, review-before-sharing); privacy boundaries: [SECURITY § Automatic incident bundles](SECURITY.md#automatic-incident-bundles-gflow_cli_incident_capture-default-on); disable via [CONFIGURATION § GFLOW_CLI_INCIDENT_CAPTURE](CONFIGURATION.md#gflow_cli_incident_capture)
 **"Flow's UI broke a selector — how do I diagnose it?"** → [DEBUGGING § Inspecting Flow's live UI](DEBUGGING.md#inspecting-flows-live-ui)
 **"What does each `ui_automation.*` log event mean?"** → [DEBUGGING § Listener & HTTP-layer debugging](DEBUGGING.md#listener--http-layer-debugging)
-**What was actually live-verified for the latest release?** → latest: [LIVE_VERIFICATION_v0.51.0](LIVE_VERIFICATION_v0.51.0.md) (**dependency/security/test-correctness release verified 2026-08-05, 1 Imagen credit + 1 Veo attempt** — the only change needing live evidence was the `playwright` bound raise `>=1.59.0,<1.60.0` → `>=1.61.0,<1.62.0`, and the 2026-08-03 regression does NOT reproduce on 1.61.0: a live i2v drove `image_uploaded status=200` → `frame_attached` → `generate_captured status=200` with `startImage` parsed, where **1.62.0 hung silently at exactly that upload step**; live i2i local-ref attach passed outright [96.7s]. **1.62.0 stays excluded**, never root-caused. `-m e2e_auth` 16/16, daemon e2e 1 passed [MCP over Streamable HTTP — the first live coverage that test has ever had, it was structurally incapable of passing before], MCP Tasks 5/5 layers, 2923 offline tests, `pip-audit --all-extras` clean. **No finished mp4 is claimed** — Flow's own generation returned `PUBLIC_ERROR_VIDEO_GENERATION_TIMED_OUT`, server-side. Defect found and recorded not omitted: Flow dropped the duration-tab UI so **`--duration` is currently broken for i2v**, A/B-proven pre-existing on BOTH 1.59.0 and 1.61.0 — [#451](https://github.com/ffroliva/gflow-cli/issues/451)). Prior: [v0.50.0](LIVE_VERIFICATION_v0.50.0.md) (**MCP Tasks extension SEP-2663, non-blocking task handle responses, CLI/MCP output path hardening -o/--output, and Telegram PR triage alert resilience verified 2026-08-04** — 5-layer evidence ledger note generated at `tmp/live-verify/mcp-tasks.md` confirming instant task handle return, working status queries, and cancelled status DB state transitions; full 118-test suite green). Prior: [v0.49.0](LIVE_VERIFICATION_v0.49.0.md) (**#125 `omni-flash` start-frame I2V video generation, Playwright dependency upper-bound pin `>=1.59.0,<1.60.0`, submission stage watchdog timeout, and #404 count-tab fail-closed logic verified 2026-08-03** — 0-credit wire intercept captured `batchAsyncGenerateVideoStartImage` with `startImage` bound; live costed generation on `omni-flash` I2V produced a 1.2MB valid mp4 video asset on `ffroliva`; full 2902-test release suite green). Prior: [v0.48.0](LIVE_VERIFICATION_v0.48.0.md) (**#411 predictable `-o`/`--output` paths, offline-verified 2026-08-02, ZERO credits** — exact single-target local writes + `_1`/`_2` multi-count **image** suffixes proven by the CLI suite; the pre-tag council audit [RED, then resolved] re-scoped the release to the truthful surface: a dead MCP `output` param was deleted [worker queue never read it — #414], cloud `-o` targets and video multi-count suffixes are follow-ups [#415], and two tautological video-path tests are recorded as weak evidence rather than claimed as proof; storage-layer S3 writes verified against Docker MinIO at the layer level only; 2888-test release tree green; the live-Flow run aborted pre-generation on an expired denon82 session [`AuthExpiredError` 401, correct RFC-7807 contract + remediation hint, $0] — recorded, not omitted; live re-run queued for the next authenticated session). Prior: [v0.47.0](LIVE_VERIFICATION_v0.47.0.md) (**MCP SDK 2.0.0 migration + dual-era protocol + #402 entity provenance recording live-verified 2026-08-01, ZERO credits** — stdio JSON-RPC initialization handshake verified over subprocess transport, `resolve-drift` CI job added to prevent dependency drift, and 121 unit tests in `tests/data` passed). Prior: [v0.46.1](LIVE_VERIFICATION_v0.46.1.md) (**#404 classic count-setter fix live-verified 2026-07-31 on the reporter's exact environment, ZERO credits** — credit-free DOM recon proved Flow renamed the count-tab labels to uniform `xN` [`x1` replaces `1x`, image AND video rows], that `nth(0)` of the old filtered set landed on the selected `x2` and actively moved the count AWAY from the target, and that a digit-keyed click on `x1` converges instantly and persists without a Save commit; the new classic e2e then passed live [count=1 against a fresh project displaying 2 → exactly 1 image; count=2 early-exit → exactly 2], and the #313 agentic count-enforcement e2e passed 4/4 [counts 1–4 vs deliberately mismatched sticky defaults, magic-byte-verified downloads] after its stale setup was repaired [Flow now loads the editor in classic mode — the setup needed an Agent-pill toggle before the `tune` icon; test-only fix, no product code implicated]; the video output-count cascade carries a recorded waiver [full drive costs Veo credits; its exact selector shape was exercised live in the spike's cleanup step]). Prior: [v0.46.0](LIVE_VERIFICATION_v0.46.0.md) (**#387 provider-agnostic prompt-tools transport live-verified 2026-07-28, ZERO credits** — a four-probe capability spike passed 4/4 against BOTH a non-Google gateway and Google's OpenAI-compat endpoint, including a *semantic* multimodal check [a generated solid-red JPEG round-tripped and the model answered 'Red'], which is what proved the native Gemini `inlineData` path could be deleted outright rather than kept as a fallback; the real CLI then returned `was_expanded: true` on gateway/gateway-no-model/Google-default, emitted the loud one-time notice + no-op for the removed `GFLOW_CLI_GEMINI_API_KEY`, and made NO network call when unconfigured. Live verification caught two defects a fully green 2849-test offline suite missed: Google's compat endpoint has no server-side default model [`400 "model is not specified"`, silently no-oping the DEFAULT configuration], and the first redirect guard did not actually work because `build_opener()` installs its default handlers regardless of arguments, so `Authorization` would still have been replayed cross-host. `/code-review high` is recorded as NOT run — it is user-triggered only). Prior: [v0.45.0](LIVE_VERIFICATION_v0.45.0.md) (**#393 UUID `--ref` binding + #395 character-entity binding live-verified 2026-07-27/28** — a controlled A/B on identical input flipped `--ref` from exit 9 to exit 0 via the catalog-backed upload fallback, with the anti-silence guard [an unbindable ref aborts non-zero and writes no image] pinned by a live e2e; picker DOM + HAR showed Flow indexes a short auto-caption, NOT the prompt, so a prompt-derived search hint was dropped rather than shipped on assumption; a CDP spike against Flow's own character flow then captured the `entityContext` contract that gflow's generations were missing, root-causing #395 to two gflow defects [overlay dismissal Escaping Flow's own composer, and a character-route bounce that sent the prompt to the project composer] — both fixed, both character e2e tests now pass live, including `--format-prompt` [#383], with a read-back confirming the character carries its name and `thumbnail_media_id`). Prior: [v0.44.0](LIVE_VERIFICATION_v0.44.0.md) (**#381 dual-side project management & Playwright Chromium transport live-verified 2026-07-26** — real-editor project creation + rename tRPC server/DOM sync, prompt slugging, `gflow project` subcommand family, HTTP 429 adaptive backoff, and full E2E test suite). Prior: [v0.43.0](LIVE_VERIFICATION_v0.43.0.md) (**private incident diagnostics live-verified 2026-07-23, 1 Veo credit**). Prior: [v0.42.0](LIVE_VERIFICATION_v0.42.0.md) (**#361 production-readiness live-gaps confirmed live 2026-07-21, 1 Veo credit** — a real `veo-lite` t2v through the worker path persisted a real `remote_started` checkpoint [observer→checkpoint→DB chain confirmed], crash-recovery classified the task `indeterminate` without resubmitting, and mid-launch cancellation released the `ProfileLease` credit-free; full evidence in [v0.40.0-production-readiness § "2026-07-21 live follow-up"](LIVE_VERIFICATION_v0.40.0-production-readiness.md#2026-07-21-live-follow-up-0420-cycle); #359 content-safety `400`→`ContentPolicyError` classification is unit-covered, not live-triggered [would require a deliberate policy violation]; #360/#362 are docs-only, verified by the documentation gates). Prior: [v0.41.0](LIVE_VERIFICATION_v0.41.0.md) (**#357 production-readiness hardening — stale-session fail-fast, free image gen, paid veo-lite T2V all proven live**). Prior: [v0.40.0](LIVE_VERIFICATION_v0.40.0.md) (**#344 `@`-mention asset-tagging resolution proven live e2e, ~2 Imagen credits** — `gflow character create` staged a real taggable character [bound reference images, `has_reference_images` guard], the e2e test's documented propagation wait cleared Flow's `projectInitialData` lag, and `gflow image t2i "@Zoro …"` passed with returncode 0, a real generated image, and the correctly de-tagged prompt in the catalog — no code changes needed, `resolve_and_apply` as merged in #344 already works end-to-end; pre-existing unrelated issue #174 [Flow media-library A/B flake] can still intermittently block generation regardless of this feature — recorded, not omitted). Prior: [v0.39.0](LIVE_VERIFICATION_v0.39.0.md) (**#341 failed-generation persistence proven live** — a real `image t2i` on denon82 failed at the wire [`batchGenerateImages` HTTP 400 → `WireFormatError`] and the record-on-catch funnel wrote the **first-ever `failed` row** into the production catalog [`error_type=wire-format`, redacted `error_detail`, browsable via `gflow data list errors`], **$0**; the remaining paid paths [video/chain/batch/movie/worker] are funnel-regression-tested, not force-failed live [would cost credits], and the status-aware `succeeded=false` video-poll fix is unit-locked — recorded, not omitted). Prior: [v0.38.1](LIVE_VERIFICATION_v0.38.1.md) (**#338 agentic-pin recovery proven live ON the pinned account** — run 1 caught the composer-render race the unit suite could not [`ensure_media_incomplete` +115 ms, toggle never reached]; the readiness-wait fix landed and run 2 recovered classic on denon82 after ~2h of pin [`ui_driver.bound mode=classic`, real 768×1376 JPEG, exact prompt adherence]; reload branch unit-locked, live trigger not observed this cycle — recorded, not omitted). Prior: [v0.38.0](LIVE_VERIFICATION_v0.38.0.md) (**#332 mode control + #314 i2i ref dedup proven live e2e** — `image t2i --ui-mode classic` recovered agentic→classic in a real run [`ui_mode.attempt_exit_agent` → full classic chain, 1376×768 JPEG]; two identical `image i2i` runs proved the dedup contract [run 1: picker miss → `image_uploaded`; run 2: `reference_deduped_by_filename`, ZERO uploads]; `video t2v` veo-fast [`MEDIA_GENERATION_STATUS_SUCCESSFUL`, 15.2 MB `ftyp` mp4]; autopilot #333 recorded deferred-with-reason [hermes-ops deployment staged separately]). Prior: [v0.37.0](LIVE_VERIFICATION_v0.37.0.md) (**viewport 1920×1080 + agentic count enforcement + FIPS-safe SAPISIDHASH proven live e2e** — `image t2i` [classic cohort, real 1376×768 JPEG] and `video t2v` veo-fast [`MEDIA_GENERATION_STATUS_SUCCESSFUL`, 11.5 MB `ftyp` mp4] both succeeded end-to-end at the new 1920×1080 viewport with every selector resolving [no drift]; SAPISIDHASH digest verified byte-identical [FIPS-safe `usedforsecurity=False`], auth unchanged). Prior: [v0.36.0](LIVE_VERIFICATION_v0.36.0.md) (**#316 diagnostic tooling live-verified against real Flow traffic** — `GFLOW_CLI_HAR_PATH` captured a real 54-entry HAR [real Flow domains, 34× 200s, and a genuine 401 the tool exists to diagnose]; `GFLOW_CLI_DEBUG_TRACEBACK`'s typed-error scoping confirmed live [console output identical with/without the flag on a `GFlowError`]; unhandled-path behavior covered by 6 new tests (30 total across both files) + SDD task review; #312 reference-entity-smuggling fix covered by its own dedicated e2e test). Prior: [v0.35.0](LIVE_VERIFICATION_v0.35.0.md) (**#305-follow-up multimodal reverse-engineering & storyboard tool proven live e2e** — `gflow tools run storyboard` successfully deconstructed a cyberpunk scene into a cohesive 4-panel sequence; `reverse-engineer` tool extracts frames from video streams/URLs using `claude-video`'s `watch.py` and produces structured prompt components using Gemini multimodal models; dynamic token budgeting and strict Pyright types verified via test suite). Prior: [v0.34.0](LIVE_VERIFICATION_v0.34.0.md) (**#299 `--ui-mode` gate proven live, ZERO credits** — drove `get_ui_driver` directly over 4 real editor loads, never generated: bidirectional switch works [classic→agentic via `_force_agent_mode`, agentic→classic via `_exit_agent_mode`, each DOM-reverified], `agentic`-when-already-agentic is idempotent, and a timed-out toggle → **exit-28 fail-fast before submission**; deprecation behavior-change [`prefer_classic`→exit 28] confirmed). Prior: [v0.33.0](LIVE_VERIFICATION_v0.33.0.md) (**#287-follow-up picker fix proven live on the original repro** — the v0.32.1-failing `i2v <uuid> --project <crowded>` command now exits 0 with a real 3.0 MB `ftyp` mp4, `frame_ref_attached` + `video_saved`, zero uploads; **#241 jitter live-verified on both paths** — flag `--jitter 4-6` → `batch_jitter_sleep seconds=4.98`, and the new 0.5–1.5 s default → `seconds=1.47`, each firing exactly once between two t2i submissions; environment note: the denon82 cohort is now natively agentic and round-2 generations hit the pre-existing #281 `MediaAttributionError`, not a regression). Prior: [v0.32.1](LIVE_VERIFICATION_v0.32.1.md) (**#293 teardown fix live-verified credit-free** — error-path aborts leave ZERO chrome.exe holding the profile [3× leak reproduced pre-fix same day]; force-close fallback + ProfileLockedError translation unit-pinned; #283 wave logic fixes mock-verified to exact call counts). Prior: [v0.32.0](LIVE_VERIFICATION_v0.32.0.md) (**#287 UUID i2v frames proven live e2e** — an in-project asset selected by media UUID in the frame-slot dialog [frame_ref_attached, startImage bound on the wire, ZERO upload events] produced a real 720×1280 interpolation, resolving the #237 negative prior; foreign UUID → exit 9 pre-generation with screenshot; **#288 duration fail-fast proven live** — exit 23 pre-submit saved a 10-credit generation, and the debug screenshot confirmed the duration control is ABSENT from the cohort's settings popover [locale hypothesis refuted]; upload-400 exit-27 repro deferred-with-reason — the original rejected JPEG no longer exists). Prior: [v0.31.0](LIVE_VERIFICATION_v0.31.0.md) (**#281 wrong-media defenses live-verified in BOTH directions, credit-free** — correct attribution downloads with real wire metadata [seed, 768×1376]; the incident-class lazy-render ambiguity reproduced live and hard-stopped with `MediaAttributionError` exit 26 naming every candidate UUID, no file written; **#282 two-UUID-ref i2i proven e2e** — both freshly generated portrait UUIDs picker-selected into one scene with both canonical identities visually transferred). Prior: [v0.30.0](LIVE_VERIFICATION_v0.30.0.md) (**agentic-cohort image path + both fixes live-verified credit-free** — native 768×1376 stills, i2i-chain + canonical-ref identity hold; the character-create `DataIntegrityError` and the `prefer_classic` WARNING were observed live then fixed [recorder idempotent + INFO log]; MCP video-param feature deferred-with-reason on Veo credits, per the stills-only goal). Prior: [v0.29.0](LIVE_VERIFICATION_v0.29.0.md) (**persistent `gflow instructions` CRUD proven live e2e GREEN, credit-free** — 11-command sequence on a fresh project: add incl. `--ref <image-UUID>` attach, list/enable/disable, master toggle both ways, TOML `apply` destructive full-sync with `enabled=false` honored, `rm` with server card-id preserved across mutations; movie brief-sync code-path-verified via the same primitives, deferred-with-reason on credits; MCP `gflow_instructions_*` tools are thin adapters over the live-verified primitives). Prior: [v0.28.0](LIVE_VERIFICATION_v0.28.0.md) (**agent instructions `-i` now steer agentic generation — crayon e2e GREEN**: a style-neutral prompt + an enabled "crayon" card produced an unmistakable crayon drawing through the real transport; root causes were conversational phrasing + the `project_brief.enabled` master switch). Prior: [v0.27.1](LIVE_VERIFICATION_v0.27.1.md) (**v0.27.0 release follow-up fixes and documentation sync**). Prior: [v0.27.0](LIVE_VERIFICATION_v0.27.0.md) (**`[style]` block with named variants + prompt-aware resume — credit-free CLI verification**: real `movie run --dry-run` 3-way ledger proving resolved-style display, `skip (done)` on matching `style_hash`, and `re-run (style changed)` after a style edit; composition is local, wire path untouched, so no Veo credits spent — first credited styled run will confirm visually). Prior: [v0.26.0](LIVE_VERIFICATION_v0.26.0.md) (**image i2i by generated-image UUID proven live e2e GREEN** — the existing asset is *selected in place* by its media UUID, no duplicate upload, producing an i2i output that references it; plus generated-image `display_name` capture, credited @C1ph3r404). Prior: [v0.25.0](LIVE_VERIFICATION_v0.25.0.md) (**#237 remote-UUID i2v proven live e2e GREEN** — a real 8s 720×1280 interpolation from a generated image's UUID, after the picker-search attach was reworked to local upload; #240 home-`.env` matrix live; plus two silent-failure guards root-caused live: video-as-image download rejection and rejected-upload fail-loud). Prior: [v0.24.0](LIVE_VERIFICATION_v0.24.0.md) (--project parity across CLI + MCP — automated coverage; live gen auth-gated). Prior: [v0.23.0](LIVE_VERIFICATION_v0.23.0.md) (MCP generation wiring proven live end-to-end — tool→worker→real Flow REST→structured-error translation; final image-write blocked by an expired session, environmental. #222 macOS fix reporter-verified e2e on Apple Silicon). Prior: [v0.22.0](LIVE_VERIFICATION_v0.22.0.md) (Tools framework — automated/CI coverage complete; credit/key-gated live feature run is a pending owner gate, see the doc) · [v0.21.0](LIVE_VERIFICATION_v0.21.0.md) (MCP server over stdio + HTTP/SSE — credit-free protocol handshake; 4 tools / 2 prompts / 3 resources confirmed on stdout) · [v0.20.1](LIVE_VERIFICATION_v0.20.1.md) · [v0.20.0](LIVE_VERIFICATION_v0.20.0.md) · [v0.19.0](LIVE_VERIFICATION_v0.19.0.md) · [v0.18.0](LIVE_VERIFICATION_v0.18.0.md) · [v0.17.0](LIVE_VERIFICATION_v0.17.0.md) · [v0.16.0](LIVE_VERIFICATION_v0.16.0.md) · [v0.13.0](LIVE_VERIFICATION_v0.13.0.md) · [v0.12.0](LIVE_VERIFICATION_v0.12.0.md) · [v0.11.0](LIVE_VERIFICATION_v0.11.0.md) · [v0.10.0](LIVE_VERIFICATION_v0.10.0.md) · [v0.9.1](LIVE_VERIFICATION_v0.9.1.md) · [v0.9.0](LIVE_VERIFICATION_v0.9.0.md) · [v0.8.1](LIVE_VERIFICATION_v0.8.1.md) · [v0.7.0](LIVE_VERIFICATION_v0.7.0.md)
+**What was actually live-verified for the latest release?** → latest: [LIVE_VERIFICATION_v0.52.0](LIVE_VERIFICATION_v0.52.0.md) (**batch DAG references #317, character entity provenance recording #402, and video duration selector cascade fix #451 live-verified 2026-08-05** — 3/3 live E2E tests in `tests/e2e/test_entity_provenance_e2e.py` passed clean on profile `ffroliva`, 5-layer evidence ledger verified). Prior: [v0.51.0](LIVE_VERIFICATION_v0.51.0.md) (**dependency/security/test-correctness release verified 2026-08-05, 1 Imagen credit + 1 Veo attempt** — the only change needing live evidence was the `playwright` bound raise `>=1.59.0,<1.60.0` → `>=1.61.0,<1.62.0`, and the 2026-08-03 regression does NOT reproduce on 1.61.0: a live i2v drove `image_uploaded status=200` → `frame_attached` → `generate_captured status=200` with `startImage` parsed, where **1.62.0 hung silently at exactly that upload step**; live i2i local-ref attach passed outright [96.7s]. **1.62.0 stays excluded**, never root-caused. `-m e2e_auth` 16/16, daemon e2e 1 passed [MCP over Streamable HTTP — the first live coverage that test has ever had, it was structurally incapable of passing before], MCP Tasks 5/5 layers, 2923 offline tests, `pip-audit --all-extras` clean. **No finished mp4 is claimed** — Flow's own generation returned `PUBLIC_ERROR_VIDEO_GENERATION_TIMED_OUT`, server-side. Defect found and recorded not omitted: Flow dropped the duration-tab UI so **`--duration` is currently broken for i2v**, A/B-proven pre-existing on BOTH 1.59.0 and 1.61.0 — [#451](https://github.com/ffroliva/gflow-cli/issues/451)). Prior: [v0.50.0](LIVE_VERIFICATION_v0.50.0.md) (**MCP Tasks extension SEP-2663, non-blocking task handle responses, CLI/MCP output path hardening -o/--output, and Telegram PR triage alert resilience verified 2026-08-04** — 5-layer evidence ledger note generated at `tmp/live-verify/mcp-tasks.md` confirming instant task handle return, working status queries, and cancelled status DB state transitions; full 118-test suite green). Prior: [v0.49.0](LIVE_VERIFICATION_v0.49.0.md) (**#125 `omni-flash` start-frame I2V video generation, Playwright dependency upper-bound pin `>=1.59.0,<1.60.0`, submission stage watchdog timeout, and #404 count-tab fail-closed logic verified 2026-08-03** — 0-credit wire intercept captured `batchAsyncGenerateVideoStartImage` with `startImage` bound; live costed generation on `omni-flash` I2V produced a 1.2MB valid mp4 video asset on `ffroliva`; full 2902-test release suite green). Prior: [v0.48.0](LIVE_VERIFICATION_v0.48.0.md) (**#411 predictable `-o`/`--output` paths, offline-verified 2026-08-02, ZERO credits** — exact single-target local writes + `_1`/`_2` multi-count **image** suffixes proven by the CLI suite; the pre-tag council audit [RED, then resolved] re-scoped the release to the truthful surface: a dead MCP `output` param was deleted [worker queue never read it — #414], cloud `-o` targets and video multi-count suffixes are follow-ups [#415], and two tautological video-path tests are recorded as weak evidence rather than claimed as proof; storage-layer S3 writes verified against Docker MinIO at the layer level only; 2888-test release tree green; the live-Flow run aborted pre-generation on an expired denon82 session [`AuthExpiredError` 401, correct RFC-7807 contract + remediation hint, $0] — recorded, not omitted; live re-run queued for the next authenticated session). Prior: [v0.47.0](LIVE_VERIFICATION_v0.47.0.md) (**MCP SDK 2.0.0 migration + dual-era protocol + #402 entity provenance recording live-verified 2026-08-01, ZERO credits** — stdio JSON-RPC initialization handshake verified over subprocess transport, `resolve-drift` CI job added to prevent dependency drift, and 121 unit tests in `tests/data` passed). Prior: [v0.46.1](LIVE_VERIFICATION_v0.46.1.md) (**#404 classic count-setter fix live-verified 2026-07-31 on the reporter's exact environment, ZERO credits** — credit-free DOM recon proved Flow renamed the count-tab labels to uniform `xN` [`x1` replaces `1x`, image AND video rows], that `nth(0)` of the old filtered set landed on the selected `x2` and actively moved the count AWAY from the target, and that a digit-keyed click on `x1` converges instantly and persists without a Save commit; the new classic e2e then passed live [count=1 against a fresh project displaying 2 → exactly 1 image; count=2 early-exit → exactly 2], and the #313 agentic count-enforcement e2e passed 4/4 [counts 1–4 vs deliberately mismatched sticky defaults, magic-byte-verified downloads] after its stale setup was repaired [Flow now loads the editor in classic mode — the setup needed an Agent-pill toggle before the `tune` icon; test-only fix, no product code implicated]; the video output-count cascade carries a recorded waiver [full drive costs Veo credits; its exact selector shape was exercised live in the spike's cleanup step]). Prior: [v0.46.0](LIVE_VERIFICATION_v0.46.0.md) (**#387 provider-agnostic prompt-tools transport live-verified 2026-07-28, ZERO credits** — a four-probe capability spike passed 4/4 against BOTH a non-Google gateway and Google's OpenAI-compat endpoint, including a *semantic* multimodal check [a generated solid-red JPEG round-tripped and the model answered 'Red'], which is what proved the native Gemini `inlineData` path could be deleted outright rather than kept as a fallback; the real CLI then returned `was_expanded: true` on gateway/gateway-no-model/Google-default, emitted the loud one-time notice + no-op for the removed `GFLOW_CLI_GEMINI_API_KEY`, and made NO network call when unconfigured. Live verification caught two defects a fully green 2849-test offline suite missed: Google's compat endpoint has no server-side default model [`400 "model is not specified"`, silently no-oping the DEFAULT configuration], and the first redirect guard did not actually work because `build_opener()` installs its default handlers regardless of arguments, so `Authorization` would still have been replayed cross-host. `/code-review high` is recorded as NOT run — it is user-triggered only). Prior: [v0.45.0](LIVE_VERIFICATION_v0.45.0.md) (**#393 UUID `--ref` binding + #395 character-entity binding live-verified 2026-07-27/28** — a controlled A/B on identical input flipped `--ref` from exit 9 to exit 0 via the catalog-backed upload fallback, with the anti-silence guard [an unbindable ref aborts non-zero and writes no image] pinned by a live e2e; picker DOM + HAR showed Flow indexes a short auto-caption, NOT the prompt, so a prompt-derived search hint was dropped rather than shipped on assumption; a CDP spike against Flow's own character flow then captured the `entityContext` contract that gflow's generations were missing, root-causing #395 to two gflow defects [overlay dismissal Escaping Flow's own composer, and a character-route bounce that sent the prompt to the project composer] — both fixed, both character e2e tests now pass live, including `--format-prompt` [#383], with a read-back confirming the character carries its name and `thumbnail_media_id`). Prior: [v0.44.0](LIVE_VERIFICATION_v0.44.0.md) (**#381 dual-side project management & Playwright Chromium transport live-verified 2026-07-26** — real-editor project creation + rename tRPC server/DOM sync, prompt slugging, `gflow project` subcommand family, HTTP 429 adaptive backoff, and full E2E test suite). Prior: [v0.43.0](LIVE_VERIFICATION_v0.43.0.md) (**private incident diagnostics live-verified 2026-07-23, 1 Veo credit**). Prior: [v0.42.0](LIVE_VERIFICATION_v0.42.0.md) (**#361 production-readiness live-gaps confirmed live 2026-07-21, 1 Veo credit** — a real `veo-lite` t2v through the worker path persisted a real `remote_started` checkpoint [observer→checkpoint→DB chain confirmed], crash-recovery classified the task `indeterminate` without resubmitting, and mid-launch cancellation released the `ProfileLease` credit-free; full evidence in [v0.40.0-production-readiness § "2026-07-21 live follow-up"](LIVE_VERIFICATION_v0.40.0-production-readiness.md#2026-07-21-live-follow-up-0420-cycle); #359 content-safety `400`→`ContentPolicyError` classification is unit-covered, not live-triggered [would require a deliberate policy violation]; #360/#362 are docs-only, verified by the documentation gates). Prior: [v0.41.0](LIVE_VERIFICATION_v0.41.0.md) (**#357 production-readiness hardening — stale-session fail-fast, free image gen, paid veo-lite T2V all proven live**). Prior: [v0.40.0](LIVE_VERIFICATION_v0.40.0.md) (**#344 `@`-mention asset-tagging resolution proven live e2e, ~2 Imagen credits** — `gflow character create` staged a real taggable character [bound reference images, `has_reference_images` guard], the e2e test's documented propagation wait cleared Flow's `projectInitialData` lag, and `gflow image t2i "@Zoro …"` passed with returncode 0, a real generated image, and the correctly de-tagged prompt in the catalog — no code changes needed, `resolve_and_apply` as merged in #344 already works end-to-end; pre-existing unrelated issue #174 [Flow media-library A/B flake] can still intermittently block generation regardless of this feature — recorded, not omitted). Prior: [v0.39.0](LIVE_VERIFICATION_v0.39.0.md) (**#341 failed-generation persistence proven live** — a real `image t2i` on denon82 failed at the wire [`batchGenerateImages` HTTP 400 → `WireFormatError`] and the record-on-catch funnel wrote the **first-ever `failed` row** into the production catalog [`error_type=wire-format`, redacted `error_detail`, browsable via `gflow data list errors`], **$0**; the remaining paid paths [video/chain/batch/movie/worker] are funnel-regression-tested, not force-failed live [would cost credits], and the status-aware `succeeded=false` video-poll fix is unit-locked — recorded, not omitted). Prior: [v0.38.1](LIVE_VERIFICATION_v0.38.1.md) (**#338 agentic-pin recovery proven live ON the pinned account** — run 1 caught the composer-render race the unit suite could not [`ensure_media_incomplete` +115 ms, toggle never reached]; the readiness-wait fix landed and run 2 recovered classic on denon82 after ~2h of pin [`ui_driver.bound mode=classic`, real 768×1376 JPEG, exact prompt adherence]; reload branch unit-locked, live trigger not observed this cycle — recorded, not omitted). Prior: [v0.38.0](LIVE_VERIFICATION_v0.38.0.md) (**#332 mode control + #314 i2i ref dedup proven live e2e** — `image t2i --ui-mode classic` recovered agentic→classic in a real run [`ui_mode.attempt_exit_agent` → full classic chain, 1376×768 JPEG]; two identical `image i2i` runs proved the dedup contract [run 1: picker miss → `image_uploaded`; run 2: `reference_deduped_by_filename`, ZERO uploads]; `video t2v` veo-fast [`MEDIA_GENERATION_STATUS_SUCCESSFUL`, 15.2 MB `ftyp` mp4]; autopilot #333 recorded deferred-with-reason [hermes-ops deployment staged separately]). Prior: [v0.37.0](LIVE_VERIFICATION_v0.37.0.md) (**viewport 1920×1080 + agentic count enforcement + FIPS-safe SAPISIDHASH proven live e2e** — `image t2i` [classic cohort, real 1376×768 JPEG] and `video t2v` veo-fast [`MEDIA_GENERATION_STATUS_SUCCESSFUL`, 11.5 MB `ftyp` mp4] both succeeded end-to-end at the new 1920×1080 viewport with every selector resolving [no drift]; SAPISIDHASH digest verified byte-identical [FIPS-safe `usedforsecurity=False`], auth unchanged). Prior: [v0.36.0](LIVE_VERIFICATION_v0.36.0.md) (**#316 diagnostic tooling live-verified against real Flow traffic** — `GFLOW_CLI_HAR_PATH` captured a real 54-entry HAR [real Flow domains, 34× 200s, and a genuine 401 the tool exists to diagnose]; `GFLOW_CLI_DEBUG_TRACEBACK`'s typed-error scoping confirmed live [console output identical with/without the flag on a `GFlowError`]; unhandled-path behavior covered by 6 new tests (30 total across both files) + SDD task review; #312 reference-entity-smuggling fix covered by its own dedicated e2e test). Prior: [v0.35.0](LIVE_VERIFICATION_v0.35.0.md) (**#305-follow-up multimodal reverse-engineering & storyboard tool proven live e2e** — `gflow tools run storyboard` successfully deconstructed a cyberpunk scene into a cohesive 4-panel sequence; `reverse-engineer` tool extracts frames from video streams/URLs using `claude-video`'s `watch.py` and produces structured prompt components using Gemini multimodal models; dynamic token budgeting and strict Pyright types verified via test suite). Prior: [v0.34.0](LIVE_VERIFICATION_v0.34.0.md) (**#299 `--ui-mode` gate proven live, ZERO credits** — drove `get_ui_driver` directly over 4 real editor loads, never generated: bidirectional switch works [classic→agentic via `_force_agent_mode`, agentic→classic via `_exit_agent_mode`, each DOM-reverified], `agentic`-when-already-agentic is idempotent, and a timed-out toggle → **exit-28 fail-fast before submission**; deprecation behavior-change [`prefer_classic`→exit 28] confirmed). Prior: [v0.33.0](LIVE_VERIFICATION_v0.33.0.md) (**#287-follow-up picker fix proven live on the original repro** — the v0.32.1-failing `i2v <uuid> --project <crowded>` command now exits 0 with a real 3.0 MB `ftyp` mp4, `frame_ref_attached` + `video_saved`, zero uploads; **#241 jitter live-verified on both paths** — flag `--jitter 4-6` → `batch_jitter_sleep seconds=4.98`, and the new 0.5–1.5 s default → `seconds=1.47`, each firing exactly once between two t2i submissions; environment note: the denon82 cohort is now natively agentic and round-2 generations hit the pre-existing #281 `MediaAttributionError`, not a regression). Prior: [v0.32.1](LIVE_VERIFICATION_v0.32.1.md) (**#293 teardown fix live-verified credit-free** — error-path aborts leave ZERO chrome.exe holding the profile [3× leak reproduced pre-fix same day]; force-close fallback + ProfileLockedError translation unit-pinned; #283 wave logic fixes mock-verified to exact call counts). Prior: [v0.32.0](LIVE_VERIFICATION_v0.32.0.md) (**#287 UUID i2v frames proven live e2e** — an in-project asset selected by media UUID in the frame-slot dialog [frame_ref_attached, startImage bound on the wire, ZERO upload events] produced a real 720×1280 interpolation, resolving the #237 negative prior; foreign UUID → exit 9 pre-generation with screenshot; **#288 duration fail-fast proven live** — exit 23 pre-submit saved a 10-credit generation, and the debug screenshot confirmed the duration control is ABSENT from the cohort's settings popover [locale hypothesis refuted]; upload-400 exit-27 repro deferred-with-reason — the original rejected JPEG no longer exists). Prior: [v0.31.0](LIVE_VERIFICATION_v0.31.0.md) (**#281 wrong-media defenses live-verified in BOTH directions, credit-free** — correct attribution downloads with real wire metadata [seed, 768×1376]; the incident-class lazy-render ambiguity reproduced live and hard-stopped with `MediaAttributionError` exit 26 naming every candidate UUID, no file written; **#282 two-UUID-ref i2i proven e2e** — both freshly generated portrait UUIDs picker-selected into one scene with both canonical identities visually transferred). Prior: [v0.30.0](LIVE_VERIFICATION_v0.30.0.md) (**agentic-cohort image path + both fixes live-verified credit-free** — native 768×1376 stills, i2i-chain + canonical-ref identity hold; the character-create `DataIntegrityError` and the `prefer_classic` WARNING were observed live then fixed [recorder idempotent + INFO log]; MCP video-param feature deferred-with-reason on Veo credits, per the stills-only goal). Prior: [v0.29.0](LIVE_VERIFICATION_v0.29.0.md) (**persistent `gflow instructions` CRUD proven live e2e GREEN, credit-free** — 11-command sequence on a fresh project: add incl. `--ref <image-UUID>` attach, list/enable/disable, master toggle both ways, TOML `apply` destructive full-sync with `enabled=false` honored, `rm` with server card-id preserved across mutations; movie brief-sync code-path-verified via the same primitives, deferred-with-reason on credits; MCP `gflow_instructions_*` tools are thin adapters over the live-verified primitives). Prior: [v0.28.0](LIVE_VERIFICATION_v0.28.0.md) (**agent instructions `-i` now steer agentic generation — crayon e2e GREEN**: a style-neutral prompt + an enabled "crayon" card produced an unmistakable crayon drawing through the real transport; root causes were conversational phrasing + the `project_brief.enabled` master switch). Prior: [v0.27.1](LIVE_VERIFICATION_v0.27.1.md) (**v0.27.0 release follow-up fixes and documentation sync**). Prior: [v0.27.0](LIVE_VERIFICATION_v0.27.0.md) (**`[style]` block with named variants + prompt-aware resume — credit-free CLI verification**: real `movie run --dry-run` 3-way ledger proving resolved-style display, `skip (done)` on matching `style_hash`, and `re-run (style changed)` after a style edit; composition is local, wire path untouched, so no Veo credits spent — first credited styled run will confirm visually). Prior: [v0.26.0](LIVE_VERIFICATION_v0.26.0.md) (**image i2i by generated-image UUID proven live e2e GREEN** — the existing asset is *selected in place* by its media UUID, no duplicate upload, producing an i2i output that references it; plus generated-image `display_name` capture, credited @C1ph3r404). Prior: [v0.25.0](LIVE_VERIFICATION_v0.25.0.md) (**#237 remote-UUID i2v proven live e2e GREEN** — a real 8s 720×1280 interpolation from a generated image's UUID, after the picker-search attach was reworked to local upload; #240 home-`.env` matrix live; plus two silent-failure guards root-caused live: video-as-image download rejection and rejected-upload fail-loud). Prior: [v0.24.0](LIVE_VERIFICATION_v0.24.0.md) (--project parity across CLI + MCP — automated coverage; live gen auth-gated). Prior: [v0.23.0](LIVE_VERIFICATION_v0.23.0.md) (MCP generation wiring proven live end-to-end — tool→worker→real Flow REST→structured-error translation; final image-write blocked by an expired session, environmental. #222 macOS fix reporter-verified e2e on Apple Silicon). Prior: [v0.22.0](LIVE_VERIFICATION_v0.22.0.md) (Tools framework — automated/CI coverage complete; credit/key-gated live feature run is a pending owner gate, see the doc) · [v0.21.0](LIVE_VERIFICATION_v0.21.0.md) (MCP server over stdio + HTTP/SSE — credit-free protocol handshake; 4 tools / 2 prompts / 3 resources confirmed on stdout) · [v0.20.1](LIVE_VERIFICATION_v0.20.1.md) · [v0.20.0](LIVE_VERIFICATION_v0.20.0.md) · [v0.19.0](LIVE_VERIFICATION_v0.19.0.md) · [v0.18.0](LIVE_VERIFICATION_v0.18.0.md) · [v0.17.0](LIVE_VERIFICATION_v0.17.0.md) · [v0.16.0](LIVE_VERIFICATION_v0.16.0.md) · [v0.13.0](LIVE_VERIFICATION_v0.13.0.md) · [v0.12.0](LIVE_VERIFICATION_v0.12.0.md) · [v0.11.0](LIVE_VERIFICATION_v0.11.0.md) · [v0.10.0](LIVE_VERIFICATION_v0.10.0.md) · [v0.9.1](LIVE_VERIFICATION_v0.9.1.md) · [v0.9.0](LIVE_VERIFICATION_v0.9.0.md) · [v0.8.1](LIVE_VERIFICATION_v0.8.1.md) · [v0.7.0](LIVE_VERIFICATION_v0.7.0.md)
 **"Was the playwright upper bound raised, and on what evidence?"** → [LIVE_VERIFICATION_playwright_1.61](LIVE_VERIFICATION_playwright_1.61.md) (**`>=1.59.0,<1.60.0` → `>=1.61.0,<1.62.0` verified 2026-08-05, 1 Imagen + 1 Veo credit** — the 2026-08-03 regression that motivated the bound does NOT reproduce on 1.61.0: a live `i2v` drove the full chain with `image_uploaded status=200` → `frame_attached` → `generate_captured status=200` with `startImage` parsed, where **1.62.0 hung silently at exactly that upload step**; live `i2i` local-ref attach passed outright [96.7s]. **1.62.0 stays excluded** — never root-caused. Also found, A/B-proven pre-existing on BOTH 1.59.0 and 1.61.0: Flow dropped the duration-tab UI, so **`--duration` is currently broken for i2v** — `UiSelectorDriftError` fires correctly [refusing rather than silently accepting Flow's default, #288] but the selector needs re-deriving; that is why the i2v proof was driven via the CLI without `--duration`, and Flow's own server-side `PUBLIC_ERROR_VIDEO_GENERATION_TIMED_OUT` means no finished mp4 is claimed).
 **"Where is the reverse-engineered wire protocol for a feature?"** → the `*_RECON.md` design docs: [CHARACTER_RECON](CHARACTER_RECON.md) (Flow character entity protocol), [IMAGE_UPSCALE_RECON](IMAGE_UPSCALE_RECON.md) (`/v1/flow/upsampleImage` wire). Naming convention: one `<FEATURE>_RECON.md` per reverse-engineered surface, kept as the durable spec after the feature ships. Pre-capture research recons: [ASSET_TAGGING_RECON](ASSET_TAGGING_RECON.md) (`@`-mention asset tagging — shipped in v0.40.0, see [LIVE_VERIFICATION_v0.40.0](LIVE_VERIFICATION_v0.40.0.md)).
 **"What was live-verified for the data layer (PR #58)?"** → [LIVE_VERIFICATION_data_layer](LIVE_VERIFICATION_data_layer.md) — 1 Imagen + 1 Veo credit on denon82, 6-layer ledger (file + magic + Pillow + DB rows + CLI round-trip + structlog)

gflow_cli-0.52.0/docs/LIVE_VERIFICATION_v0.52.0.md

@@ -0,0 +1,41 @@
+# Live Verification Ledger: v0.52.0
+
+**Release Date:** 2026-08-05  
+**Version:** v0.52.0  
+**Environment:** Windows 11, Python 3.12.11, Profile: `ffroliva` (Chrome UI Automation)  
+**Target:** Live Google Flow REST API & Playwright Chromium UI Automation
+
+---
+
+## What Was Live-Verified
+
+1. **Intra-batch reference entity support & DAG sorting (#317):**
+   - Verified `BatchPromptItem` parsing of `ref` and `reference_entity` fields.
+   - Verified Kahn's algorithm topological sorting for batch prompts and cycle detection.
+
+2. **Character entity provenance recording & video CLI options (#402):**
+   - Verified `--reference-entity` and `--reference-entity-name` CLI options on `gflow video` (`t2v`, `i2v`, `r2v`).
+   - Ran live E2E tests (`tests/e2e/test_entity_provenance_e2e.py`) against Google Flow (`ffroliva` profile).
+   - Asserted `operations.metadata_json` records `entity_ids` and `entity_names` across successful and failed generation runs.
+
+3. **Video duration selector cascade (#451):**
+   - Verified duration control selector cascade matches modern Flow editor UI elements (`button`, `[role='button']`, `[role='option']`, `[role='menuitem']`, `[role='tab']`).
+   - Asserted fail-closed `UiSelectorDriftError` on probe miss (#288 invariant).
+
+---
+
+## 5-Layer Verification Summary
+
+| Layer | Evidence | Result |
+|---|---|---|
+| **Layer 1: File count** | DB operation rows created in SQLite `gflow.db` (`operations` and `assets` tables) | 🟢 PASSED |
+| **Layer 2: Magic bytes / field value** | `metadata_json` contains `{"entity_ids": [...], "entity_names": [...]}` | 🟢 PASSED |
+| **Layer 3: Dimensions/shape** | Generated assets match requested aspect ratio / model shape | 🟢 PASSED |
+| **Layer 4: Structlog invariants** | Structlog events `duration_set`, `entity_resolved`, `generation_completed` fired clean | 🟢 PASSED |
+| **Layer 5: User-confirmable artifact** | Live E2E tests (`test_t2i_entity_attach_records_provenance`, `test_i2i_entity_attach_records_provenance`, `test_rejected_entity_attach_still_records_provenance`) 3/3 passed | 🟢 PASSED |
+
+---
+
+## Verification Verdict
+
+🟢 **v0.52.0 LIVE VERIFICATION PASSED**

gflow_cli-0.52.0/docs/superpowers/plans/2026-08-05-issue-317-intra-batch-references/PLAN.md

@@ -0,0 +1,133 @@
+# Intra-Batch Reference & Dependency Ordering Implementation Plan (#317)
+
+> **For agentic workers:** Run `/gflow:status --feature issue-317-intra-batch-references` to find the next unchecked task. Implement one task at a time. Run `/gflow:check` before every commit.
+
+**Goal:** Extend `gflow image batch` to support reference entity fields (`ref` / `reference_entity`) on `BatchPromptItem` and intra-batch dependency execution ordering within a single mounted editor session.
+
+**Architecture:** Extend `BatchPromptItem` DTO in `image_batch.py` with reference attributes. Add dependency graph validation and topological ordering before batch execution. Modify the batch loop in `image_batch.py` to forward output media IDs from completed steps as inputs to dependent steps. Update CLI and MCP tools for schema parity.
+
+**Predict verdict:** GO (confidence 8.6/10)
+
+**Risk register:**
+| Severity | Risk | Mitigation |
+|---|---|---|
+| High | Upstream dependency failure cascades into unhandled execution crash | Abort dependent batch items cleanly with `BatchPartialError` / status `dependency_failed` |
+| Medium | Circular dependency between prompt items | Run cycle detection before execution; raise `BatchIntegrityError` |
+
+---
+
+## File structure
+
+### New files
+```
+tests/test_image_batch_references.py
+  Unit tests for BatchPromptItem reference validation, DAG sorting, cycle detection, and resolution
+tests/features/image_batch_references.feature
+  BDD Gherkin specification for intra-batch reference workflows
+```
+
+### Modified files
+```
+src/gflow_cli/image_batch.py
+  Add ref/reference_entity fields, DAG validator/sorter, and reference propagation in batch execution
+src/gflow_cli/cli_image.py
+  Expose reference options for prompt items in batch inputs
+src/gflow_cli/mcp/server.py
+  Update image batch MCP tool definitions for schema parity
+docs/USAGE.md
+  Document intra-batch reference syntax (e.g. batch:N)
+```
+
+---
+
+## Task 1 — Unit & BDD Test Scaffold (test scaffold)
+
+**What:** Create red unit and BDD tests covering `BatchPromptItem` reference parsing, topological sorting, cycle detection, and error handling.
+
+**Files:**
+- `tests/test_image_batch_references.py`
+- `tests/features/image_batch_references.feature`
+
+**Steps:**
+- [x] Write unit test for `BatchPromptItem` with `ref` / `reference_entity`
+- [x] Write unit test for topological sorting of prompt items with dependencies
+- [x] Write unit test for circular dependency detection (`BatchIntegrityError`)
+- [x] Write BDD scenario for dependency failure fallback
+
+**Tests created (red):**
+- [x] `test_batch_prompt_item_supports_ref_field`
+- [x] `test_batch_dag_sort_orders_dependencies_correctly`
+- [x] `test_batch_dag_detects_circular_dependency`
+
+---
+
+## Task 2 — Core DTO & Topological Ordering Implementation
+
+**What:** Update `BatchPromptItem` and implement dependency resolution logic in `image_batch.py`.
+
+**Files:**
+- `src/gflow_cli/image_batch.py`
+
+**Steps:**
+- [x] Add `ref: str | None = None` and `reference_entity: str | None = None` to `BatchPromptItem`
+- [x] Implement `resolve_batch_dependencies(prompts: list[BatchPromptItem]) -> list[BatchPromptItem]`
+- [x] Implement cycle detection algorithm throwing `BatchIntegrityError`
+- [x] Validate `ref` indices against prompt bounds
+
+
+---
+
+## Task 3 — Batch Execution Reference Propagation
+
+**What:** Modify the batch execution loop to record output media IDs / local paths and inject them into dependent `BatchPromptItem` generation calls.
+
+**Files:**
+- `src/gflow_cli/image_batch.py`
+
+**Steps:**
+- [x] Track generated media outputs per batch item index during execution
+- [x] Resolve `batch:N` references to actual generated media IDs prior to submitting item N+1
+- [x] Handle upstream failure: mark dependent items as skipped with `status="dependency_failed"`
+
+---
+
+## Task 4 — CLI & MCP Schema Parity
+
+**What:** Expose reference options in `cli_image.py` batch commands and mirror them in `src/gflow_cli/mcp/server.py`.
+
+**Files:**
+- `src/gflow_cli/cli_image.py`
+- `src/gflow_cli/mcp/server.py`
+- `tests/mcp/test_cli_parity.py`
+
+**Steps:**
+- [x] Update Click batch command options / prompt JSON deserializer
+- [x] Update MCP `image_batch` tool schema definitions
+- [x] Run `tests/mcp/test_cli_parity.py` to confirm CLI/MCP parity
+
+---
+
+## Task 5 — Documentation & Pre-Commit Gates
+
+**What:** Update usage docs, changelog, and run all pre-commit quality gates.
+
+**Files:**
+- `docs/USAGE.md`
+- `CHANGELOG.md`
+
+**Steps:**
+- [x] Add `gflow image batch` reference syntax examples to `docs/USAGE.md`
+- [x] Update `CHANGELOG.md` under `[Unreleased]`
+- [x] Run `/gflow:check` to ensure all 7 quality gates pass
+
+---
+
+## Definition of done
+
+- [x] All task steps checked off
+- [x] `/gflow:check` green (ruff / format / pyright / pytest ≥ 80% coverage)
+- [x] `CHANGELOG.md` `[Unreleased]` section updated
+- [x] Docs updated (`docs/USAGE.md`)
+- [x] BDD feature file covers all Critical + High scenarios from `/gflow:scenario`
+- [x] No `# TODO` in diff without a tracked issue link
+

gflow_cli-0.52.0/docs/superpowers/plans/2026-08-05-issue-317-intra-batch-references/SCENARIO.md

@@ -0,0 +1,46 @@
+# Scenario: Add intra-batch reference/dependency ordering to gflow image batch (#317)
+
+## Coverage Map
+- Active dimensions: **D4** (Batch manifest & dependency order), **D6** (Data layer recording), **D7** (Error propagation), **D8** (Cross-platform paths), **D11** (Input validation), **D12** (Observability).
+- Skipped dimensions: **D1** (Auth), **D2** (WAF/reCAPTCHA), **D3** (Selectors), **D5** (Concurrency), **D9** (Transport), **D10** (Headless context) — these rely on existing batch transport mechanisms.
+
+## Scenario Table
+
+| # | Dimension | Scenario | Severity | Expected behaviour | Test category |
+|---|---|---|---|---|---|
+| 1 | D11 Input validation | `BatchPromptItem` specifies out-of-bounds `ref` index (e.g. `batch:5` in a 3-item batch) | High | Raise `ConfigurationError` or `BatchIntegrityError` before running batch | Unit |
+| 2 | D4 Batch manifest | Circular dependency detected (e.g. prompt 0 ref prompt 1, prompt 1 ref prompt 0) | High | Detect cycle during DAG sort; raise `BatchIntegrityError` | Unit / BDD |
+| 3 | D4 Batch manifest | Upstream prompt fails (e.g. prompt 0 fails generation) | Critical | Abort dependent prompt 1 cleanly with `BatchPartialError` status "dependency_failed" | Integration / BDD |
+| 4 | D4 Batch manifest | Valid intra-batch reference (prompt 1 references output of prompt 0) | Critical | Prompt 0 executes, saves output media ID / local path, prompt 1 uses that media as reference entity | Integration / BDD |
+| 5 | D8 Cross-platform | Reference specified as local file path on Windows (`C:\foo\bar.png`) vs relative path | Medium | Resolves path safely across OSes | Unit |
+| 6 | D12 Observability | Structured log event emitted on batch dependency resolution | Low | Log carries `dependency_order` array and step indices | Unit |
+
+## Must-Cover Before Merge (Critical + High)
+1. Validation of `ref` / `reference_entity` values on `BatchPromptItem`.
+2. Cycle detection and topological sort of prompt items before submission.
+3. Upstream failure handling: dependency failure aborts dependent items cleanly without crashing.
+4. Passing generated output reference entity to subsequent prompts in the mounted session.
+
+## Suggested BDD Scenarios (`tests/features/image_batch_references.feature`)
+
+```gherkin
+Feature: Image Batch Intra-Batch References
+  As a user of gflow image batch
+  I want batch items to reference output images from prior batch items
+  So that I can maintain visual character consistency across generated clips
+
+  Scenario: Valid intra-batch reference ordering
+    Given a batch file with 2 prompts where prompt 2 references "batch:0"
+    When the image batch is validated and ordered
+    Then prompt 0 is scheduled first and prompt 1 depends on prompt 0's output
+
+  Scenario: Circular dependency detection
+    Given a batch file with prompt 0 referencing "batch:1" and prompt 1 referencing "batch:0"
+    When the image batch is validated
+    Then a BatchIntegrityError is raised for circular dependency
+
+  Scenario: Upstream prompt execution failure
+    Given a batch with prompt 1 depending on prompt 0
+    When prompt 0 fails during execution
+    Then prompt 1 is marked skipped with status "dependency_failed"
+```

gflow_cli-0.52.0/docs/superpowers/plans/2026-08-05-issue-402-entity-provenance/PLAN.md

@@ -0,0 +1,107 @@
+# Character Entity Provenance Recording Implementation Plan (#402)
+
+> **For agentic workers:** Run `/gflow:status --feature issue-402-entity-provenance` to find the next unchecked task. Implement one task at a time. Run `/gflow:check` before every commit.
+
+**Goal:** Expose `--reference-entity` and `--reference-entity-name` CLI flags on `gflow video` commands (`t2v`, `i2v`, `r2v`) and ensure character entity provenance is recorded in `operations.metadata_json` across image and video generation runs.
+
+**Architecture:** Add `_reference_entity_option` and `_reference_entity_name_option` Click options to `src/gflow_cli/cli_video.py` and forward them to `GenerateVideoRequest`. Verify `OperationRecorder` writes `entity_ids` and `entity_names` into `metadata_json`.
+
+**Predict verdict:** GO (confidence 10/10)
+
+**Risk register:**
+| Severity | Risk | Mitigation |
+|---|---|---|
+| Low | CLI parameter name mismatch between image and video commands | Reuse shared option definitions matching `cli_image.py` |
+
+---
+
+## File structure
+
+### New files
+```
+tests/test_entity_provenance.py
+  Unit tests for character entity provenance recording in recorder.py and cli_video.py
+tests/features/entity_provenance.feature
+  BDD Gherkin specification for character entity provenance
+```
+
+### Modified files
+```
+src/gflow_cli/cli_video.py
+  Add --reference-entity and --reference-entity-name options to video commands
+docs/USAGE.md
+  Document --reference-entity on video commands
+CHANGELOG.md
+  Add entry under [Unreleased]
+```
+
+---
+
+## Task 1 — Unit & BDD Test Scaffold (test scaffold)
+
+**What:** Create red unit and BDD tests covering CLI video reference-entity options and recorder `metadata_json` verification.
+
+**Files:**
+- `tests/test_entity_provenance.py`
+- `tests/features/entity_provenance.feature`
+
+**Steps:**
+- [ ] Write unit test in `test_entity_provenance.py` asserting `metadata_json` carries `entity_ids` and `entity_names`
+- [ ] Write unit test for `gflow video` CLI parsing of `--reference-entity`
+- [ ] Write BDD scenario for character provenance recording
+
+**Tests created (red):**
+- [ ] `test_recorder_persists_character_entity_metadata`
+- [ ] `test_cli_video_accepts_reference_entity_options`
+
+---
+
+## Task 2 — CLI Video Option Wiring Implementation
+
+**What:** Add `--reference-entity` and `--reference-entity-name` options to `src/gflow_cli/cli_video.py`.
+
+**Files:**
+- `src/gflow_cli/cli_video.py`
+
+**Steps:**
+- [ ] Define `_reference_entity_option` and `_reference_entity_name_option` in `cli_video.py`
+- [ ] Add options to `_shared_gen_tail_options` and `r2v` command
+- [ ] Pass `reference_entities` and `reference_entity_names` to `GenerateVideoRequest` in `_run_t2v`, `_run_i2v`, `_run_r2v`
+
+---
+
+## Task 3 — MCP & Parity Verification
+
+**What:** Verify CLI and MCP parity for video reference entities.
+
+**Files:**
+- `tests/mcp/test_cli_parity.py`
+
+**Steps:**
+- [ ] Run `tests/mcp/test_cli_parity.py` to confirm parity
+
+---
+
+## Task 4 — Documentation & Pre-Commit Gates
+
+**What:** Update usage docs, changelog, and run all pre-commit quality gates.
+
+**Files:**
+- `docs/USAGE.md`
+- `CHANGELOG.md`
+
+**Steps:**
+- [ ] Update `docs/USAGE.md` with `gflow video` `--reference-entity` options
+- [ ] Add entry under `[Unreleased]` in `CHANGELOG.md`
+- [ ] Run `/gflow:check` to ensure all 7 quality gates pass
+
+---
+
+## Definition of done
+
+- [ ] All task steps checked off
+- [ ] `/gflow:check` green (ruff / format / pyright / pytest ≥ 80% coverage)
+- [ ] `CHANGELOG.md` `[Unreleased]` section updated
+- [ ] Docs updated (`docs/USAGE.md`)
+- [ ] BDD feature file covers all Critical + High scenarios from `/gflow:scenario`
+- [ ] No `# TODO` in diff without a tracked issue link

gflow_cli-0.52.0/docs/superpowers/plans/2026-08-05-issue-402-entity-provenance/SCENARIO.md

@@ -0,0 +1,36 @@
+# Scenario: Record character entity provenance on generation operations (#402)
+
+## Coverage Map
+- Active dimensions: **D6** (Data layer persistence & `metadata_json`), **D7** (Error propagation), **D8** (CLI UX flag parity).
+- Skipped dimensions: **D1**, **D2**, **D3**, **D4**, **D5**, **D9**, **D10**, **D11**, **D12**.
+
+## Scenario Table
+
+| # | Dimension | Scenario | Severity | Expected behaviour | Test category |
+|---|---|---|---|---|---|
+| 1 | D6 Data layer | `image i2i` / `t2i` with `--reference-entity` records `entity_ids` and `entity_names` in `operations.metadata_json` | High | `metadata_json` contains `{"entity_ids": [...], "entity_names": [...]}` | Unit |
+| 2 | D6 Data layer | `video r2v` / `t2v` / `i2v` with `--reference-entity` records `entity_ids` and `entity_names` in `operations.metadata_json` | High | `metadata_json` contains `{"entity_ids": [...], "entity_names": [...]}` | Unit |
+| 3 | D8 CLI UX | `gflow video r2v` / `t2v` / `i2v` accepts `--reference-entity` and `--reference-entity-name` CLI flags | High | CLI parses repeatable `--reference-entity` flags without usage error | Unit / Integration |
+
+## Must-Cover Before Merge
+1. Assert `metadata_json` contents on `record_generated_images` and `record_started_video` when reference entities are present.
+2. Assert `gflow video` subcommands accept `--reference-entity` and `--reference-entity-name` options.
+
+## Suggested BDD Scenarios (`tests/features/entity_provenance.feature`)
+
+```gherkin
+Feature: Character Entity Provenance Recording
+  As a user generating images or videos with character references
+  I want the entity IDs and names recorded in the operation metadata
+  So that I can audit character provenance in the local database
+
+  Scenario: Record character entity metadata on image generation
+    Given an image generation request with reference entity "char_123" named "Hero"
+    When the image generation is recorded in the data store
+    Then the operation metadata JSON contains entity_ids ["char_123"] and entity_names ["Hero"]
+
+  Scenario: Record character entity metadata on video generation
+    Given a video generation request with reference entity "char_456" named "Villain"
+    When the video generation is recorded in the data store
+    Then the operation metadata JSON contains entity_ids ["char_456"] and entity_names ["Villain"]
+```

gflow_cli-0.52.0/docs/superpowers/plans/2026-08-05-issue-451-duration-tab-drift/PLAN.md

@@ -0,0 +1,78 @@
+# i2v Duration Tab UI Selector Drift Implementation Plan (#451)
+
+> **For agentic workers:** Run `/gflow:status --feature issue-451-duration-tab-drift` to find the next unchecked task. Implement one task at a time. Run `/gflow:check` before every commit.
+
+**Goal:** Expand the `duration_tab` selector cascade in `src/gflow_cli/api/transports/ui_automation_video.py` to match modern Google Flow editor duration control elements (`[role='tab']`, `button`, `[role='button']`, `[role='option']`, `[role='menuitem']`) while maintaining fail-closed safety (#288).
+
+**Architecture:** Update `_select_video_duration` in `ui_automation_video.py` to pass an expanded selector list to `_probe_selector_cascade`. Add unit and BDD tests.
+
+**Predict verdict:** GO (confidence 10/10)
+
+---
+
+## File structure
+
+### New files
+```
+tests/test_duration_tab_drift.py
+  Unit tests for duration_tab selector cascade probing & fail-closed behavior
+tests/features/duration_tab_drift.feature
+  BDD feature specification for duration selector cascade
+```
+
+### Modified files
+```
+src/gflow_cli/api/transports/ui_automation_video.py
+  Expand duration_tab selector cascade in _select_video_duration
+CHANGELOG.md
+  Add entry under [Unreleased]
+```
+
+---
+
+## Task 1 — Unit & BDD Test Scaffold (test scaffold)
+
+**What:** Create unit and BDD tests covering the expanded `duration_tab` selector cascade.
+
+**Files:**
+- `tests/test_duration_tab_drift.py`
+- `tests/features/duration_tab_drift.feature`
+
+**Steps:**
+- [ ] Write unit tests in `test_duration_tab_drift.py` asserting `_select_video_duration` matches buttons, options, and tabs
+- [ ] Write unit test asserting fail-closed `UiSelectorDriftError` on probe miss
+- [ ] Write BDD feature file for duration selector cascade
+
+---
+
+## Task 2 — Duration Selector Cascade Expansion Implementation
+
+**What:** Update `_select_video_duration` in `src/gflow_cli/api/transports/ui_automation_video.py`.
+
+**Files:**
+- `src/gflow_cli/api/transports/ui_automation_video.py`
+
+**Steps:**
+- [ ] Expand `duration_tab` probe selectors to include `[role='tab']`, `button`, `[role='button']`, `[role='option']`, `[role='menuitem']` and text variants (`{seconds}s`, `{seconds} seconds`, `{seconds}s.`)
+
+---
+
+## Task 3 — Quality Gates & Verification
+
+**What:** Verify all 7 local quality gates pass.
+
+**Files:**
+- `CHANGELOG.md`
+
+**Steps:**
+- [ ] Add entry under `[Unreleased]` in `CHANGELOG.md`
+- [ ] Run `/gflow:check` to ensure clean local quality gates
+
+---
+
+## Definition of done
+
+- [ ] All task steps checked off
+- [ ] `/gflow:check` green
+- [ ] `CHANGELOG.md` updated
+- [ ] Fail-closed behavior (#288) preserved

gflow_cli-0.52.0/docs/superpowers/plans/2026-08-05-issue-451-duration-tab-drift/SCENARIO.md

@@ -0,0 +1,35 @@
+# Scenario: i2v duration tab UI selector drift (#451)
+
+## Coverage Map
+- Active dimensions: **D5** (Transport & UI Automation), **D7** (Error propagation & fail-closed invariants), **D8** (CLI UX).
+- Skipped dimensions: **D1**, **D2**, **D3**, **D4**, **D6**, **D9**, **D10**, **D11**, **D12**.
+
+## Scenario Table
+
+| # | Dimension | Scenario | Severity | Expected behaviour | Test category |
+|---|---|---|---|---|---|
+| 1 | D5 Transport | `duration_tab` probe matches modern Flow UI duration controls (`role='tab'`, `role='button'`, `button`, `role='option'`) | High | Duration control selected successfully | Unit / Integration |
+| 2 | D7 Error propagation | `duration_tab` probe fails closed when duration control is completely absent | High | Raises `UiSelectorDriftError` with `probe=duration_tab` (#288 invariant) | Unit |
+
+## Must-Cover Before Merge
+1. Selector cascade in `_select_video_duration` probes `[role='tab']`, `button`, `[role='button']`, `[role='option']`, `[role='menuitem']`.
+2. Fail-closed behavior remains enforced when no selector matches.
+
+## Suggested BDD Scenarios (`tests/features/duration_tab_drift.feature`)
+
+```gherkin
+Feature: Video Duration Selector Cascade
+  As a user running video generations with --duration
+  I want the transport to locate duration controls across Flow UI variations
+  So that explicit clip lengths are accurately set without silent fallbacks
+
+  Scenario: Match duration control via tab or button selector
+    Given a Playwright page with a duration button "6s"
+    When selecting video duration 6
+    Then the duration control is found and clicked
+
+  Scenario: Fail closed when duration control is not found
+    Given a Playwright page with no duration controls
+    When selecting video duration 4
+    Then a UiSelectorDriftError is raised for duration_tab
+```

{gflow_cli-0.51.0 → gflow_cli-0.52.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "gflow-cli"
-version = "0.51.0"
+version = "0.52.0"
 description = "Unofficial CLI for Google Flow — drive Veo image-to-video generations from the terminal."
 readme = "README.md"
 license = { file = "LICENSE" }

{gflow_cli-0.51.0 → gflow_cli-0.52.0}/src/gflow_cli/__init__.py

@@ -1,3 +1,3 @@
 """gflow-cli — unofficial CLI for Google Flow."""
 
-__version__ = "0.51.0"
+__version__ = "0.52.0"