gflow-cli 0.10.0__tar.gz → 0.12.0__tar.gz

{gflow_cli-0.10.0 → gflow_cli-0.12.0}/.claude/README.md

@@ -12,7 +12,10 @@ This directory holds **internal maintainer workflows** that are bundled with the
 └── commands/              ← repo-local slash commands
     └── gflow/             ← `/gflow:*` namespace (avoids collision with built-ins)
         ├── check.md       ← `/gflow:check` — hygiene + ruff + pyright + pytest
-        ├── plan.md        ← `/gflow:plan` — show active phase / superpowers plan
+        ├── status.md      ← `/gflow:status` — full plan state (file, goal, progress, next task)
+        ├── next.md        ← `/gflow:next` — next unchecked task only
+        ├── active.md      ← `/gflow:active` — which plan is active, goal only
+        ├── plan.md        ← `/gflow:plan <feature>` — create a task-by-task implementation plan
         ├── known-issues.md← `/gflow:known-issues` — open/mitigated items
         ├── changelog.md   ← `/gflow:changelog` — [Unreleased] + last tagged
         └── release.md     ← `/gflow:release` — full release flow (signed tags)

gflow_cli-0.12.0/.claude/commands/gflow/active.md

@@ -0,0 +1,13 @@
+---
+description: Show which plan is active and its goal — orientation without task detail.
+---
+
+# `/gflow:active` — Active plan identity
+
+**Read `skills/status/SKILL.md` and follow the `active` variant protocol.**
+
+> Do **not** call `Skill(skill="status")` — read the file directly.
+
+The skill at `skills/status/SKILL.md` runs `scripts/dev/active_plan.py` and returns
+only the header lines (Plan path, Title, Goal, Progress count). Stops before the
+`--- Next task ---` separator.

gflow_cli-0.12.0/.claude/commands/gflow/next.md

@@ -0,0 +1,12 @@
+---
+description: Show only the next unchecked task — minimal output, no context noise.
+---
+
+# `/gflow:next [feature]` — Next task
+
+**Read `skills/status/SKILL.md` and follow the `next` variant protocol**, passing `$ARGUMENTS` as the optional feature slug.
+
+> Do **not** call `Skill(skill="status")` — read the file directly.
+
+The skill at `skills/status/SKILL.md` runs `scripts/dev/active_plan.py` and returns
+only the `--- Next task ---` block. Header lines (Plan, Title, Goal, Progress) are omitted.

gflow_cli-0.12.0/.claude/commands/gflow/plan.md

@@ -0,0 +1,22 @@
+---
+description: Create a structured task-by-task implementation plan for a feature and write it to docs/superpowers/plans/.
+---
+
+# `/gflow:plan <feature>` — Create a feature plan
+
+**Read `skills/plan/SKILL.md` and follow its protocol now**, passing `$ARGUMENTS` as the feature description.
+
+> Do **not** call `Skill(skill="plan")` — the repo's `skills/*/SKILL.md` files are plain Markdown, not registered as Skill-tool-invocable. Read the file directly instead.
+
+The skill at `skills/plan/SKILL.md` gathers predict/scenario context, asks ≤3
+clarifying questions, decomposes the feature into atomic committable tasks with
+step + test checklists, and writes `docs/superpowers/plans/<date>-<slug>/PLAN.md`.
+
+**Typical workflow:**
+```
+/gflow:predict <proposal>   →  GO / CAUTION / STOP
+/gflow:scenario <feature>   →  edge cases + BDD skeleton
+/gflow:plan <feature>       →  writes PLAN.md  ← this command
+/gflow:status               →  surfaces next task
+/gflow:check                →  before each commit
+```

{gflow_cli-0.10.0 → gflow_cli-0.12.0}/.claude/commands/gflow/predict.md

@@ -16,4 +16,10 @@ The skill at `skills/predict/SKILL.md` runs five independent expert personas
 (Architect · Security/reCAPTCHA · Performance/Playwright · CLI UX · Devil's Advocate),
 resolves conflicts, and returns a GO / CAUTION / STOP verdict with a confidence score.
 
-**Pair with `/gflow:scenario`** after a GO or CAUTION to enumerate edge cases before EXECUTE.
+**Typical workflow after a GO or CAUTION:**
+```
+/gflow:scenario <feature>   →  edge cases + BDD skeleton
+/gflow:plan <feature>       →  writes PLAN.md task checklist
+/gflow:status               →  surfaces next task during execution
+/gflow:check                →  before each commit
+```

gflow_cli-0.12.0/.claude/commands/gflow/release.md

@@ -0,0 +1,241 @@
+---
+description: Cut a new gflow-cli release — bump version, update CHANGELOG, tag, push, and back-merge.
+---
+
+# `/gflow:release` — Cut a new release
+
+Follow this sequence verbatim. Every step matters.
+
+> **Branch-protection note:** `main` blocks direct pushes. The release commit travels
+> via a `chore/release-vX.Y.Z` branch PR. The signed tag is pushed independently
+> (tag pushes bypass branch protection and trigger the CI release workflow immediately).
+>
+> **Source-branch note (read first):** `develop` is the integration branch — it carries
+> ALL unreleased work and `main` usually lags it. The release branch is cut from
+> **`develop`**, NOT `main`. The PR `chore/release-vX.Y.Z → main` then brings the full
+> integration history onto `main`. Do not expect the work to already be on `main`.
+
+## Inputs
+
+Ask the user (if not already provided):
+
+1. **Version** — the new version (e.g. `0.4.0`, `0.4.0a3`, `1.0.0rc1`). Use PEP 440 prerelease suffixes (`aN`, `bN`, `rcN`). If they don't know, run `/gflow:changelog` first and propose the next bump (PATCH for fixes only, MINOR for new features, MAJOR for breaks).
+2. **Pre-release?** — prerelease versions stay marked as GitHub prereleases. Only the user can say when a release line is ready for the stable tag.
+
+---
+
+## Sequence
+
+**1. Review what's queued.**
+
+Run `/gflow:changelog` — confirm the `[Unreleased]` block is non-empty and accurate before proceeding.
+
+**2. Verify (or triage) a clean working tree.**
+
+```bash
+git status --short
+```
+
+If empty, continue. If not, **triage before aborting** — do not blindly stop:
+
+- **Auto-injected boilerplate** (e.g. a context-mode routing block appended to
+  `CLAUDE.md` by an MCP plugin's SessionStart hook): this is plugin-injected, not
+  project content — `git restore` it. Confirm with the user if unsure.
+- **Build/temp artifacts** (e.g. a stray `tmp*.tar.gz` sdist at repo root): delete them.
+- **Genuine uncommitted work:** STOP and tell the user to commit or stash on the
+  appropriate branch (never commit straight to `develop`).
+
+The tree must be clean before you create the release branch.
+
+**3. Verify `develop` is the release source and up-to-date.**
+
+The release is cut from `develop`, NOT `main` (see Source-branch note above).
+Confirm direction explicitly — a backwards divergence means a prior back-merge was skipped.
+
+```bash
+git fetch origin
+git rev-parse --abbrev-ref HEAD                      # expect "develop"
+git rev-list --count HEAD..origin/develop            # local behind origin — expect 0
+git rev-list --count origin/main..origin/develop     # develop AHEAD of main — expect > 0 (the work to release)
+git rev-list --count origin/develop..origin/main     # main AHEAD of develop — expect 0
+```
+
+If not on `develop`: `git checkout develop && git pull origin develop`.
+If local is behind origin: `git pull origin develop`.
+**If `main` is AHEAD of `develop` (last count > 0): STOP.** A prior release skipped its
+`main → develop` back-merge — recover first (see the `release-back-merge-gap-recovery`
+memory) or the release branch will hit conflicts on `pyproject.toml` / `__init__.py` / `CHANGELOG.md`.
+
+**4. Run quality gates.**
+
+Run `/gflow:check` — all gates must pass. Abort if any fail.
+
+**5. Create a release branch off `develop`.**
+
+```bash
+git checkout develop                          # ensure the base is develop, not main
+git checkout -b chore/release-v<NEW_VERSION>
+```
+
+This branch now contains all of `develop` (⊇ `main`) plus your release prep. All
+release prep commits live here; the PR into `main` (step 14) carries the full
+integration history forward.
+
+**6. Bump version** in `pyproject.toml`:
+
+```toml
+[project]
+version = "<NEW_VERSION>"
+```
+
+**7. Bump package version** in `src/gflow_cli/__init__.py`:
+
+```python
+__version__ = "<NEW_VERSION>"
+```
+
+**8. Update version assertion tests** if present:
+
+```bash
+rg -n "__version__|<OLD_VERSION>|version assertion" tests src pyproject.toml
+```
+
+**9. Migrate CHANGELOG.**
+
+- Move all entries under `## [Unreleased]` to a new `## [<NEW_VERSION>] — YYYY-MM-DD` section.
+- Leave `## [Unreleased]` empty.
+- Update the link footer. Match the repo's existing convention — every prior entry
+  uses the `compare/vPREV...vNEW` form, so use that for the new version too (NOT the
+  `releases/tag/` form), or `/gflow:doc-review` will flag the inconsistency:
+  ```
+  [Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v<NEW_VERSION>...HEAD
+  [<NEW_VERSION>]: https://github.com/ffroliva/gflow-cli/compare/v<PREV_VERSION>...v<NEW_VERSION>
+  ```
+
+**10. Run the documentation review gate.**
+
+Run `/gflow:doc-review` — audit all version refs, INDEX completeness, evidence files, skill files, CHANGELOG footer, and memory files. Fix every **FAIL** before continuing. Fold all discovered fixes into the release prep commit.
+
+**11. Commit the release prep.**
+
+```bash
+git add pyproject.toml src/gflow_cli/__init__.py uv.lock CHANGELOG.md
+git add docs/ .claude/commands/gflow/        # include any doc-review fixes
+# doc-review version-currency fixes often also touch ROOT docs — stage them too:
+git add README.md PLAN.md KNOWN_ISSUES.md AGENTS.md llms.txt 2>/dev/null || true
+git status --short                            # review EVERYTHING staged before committing
+git commit -m "chore(release): v<NEW_VERSION>"
+```
+
+- **`uv.lock` changes** on every version bump (the editable package version is
+  pinned in the lockfile) — it is easy to forget and must ship in this commit.
+- The release-prep commit must NOT carry a `Co-Authored-By` trailer (see reminders).
+
+**12. Tag the release commit.** Use `-s` for a signed annotated tag so GitHub shows **"Verified"** AND `.github/workflows/release.yml` passes the signed-tag gate (unsigned or lightweight tags are rejected by CI).
+
+```bash
+git tag -s v<NEW_VERSION> -m "v<NEW_VERSION>"
+```
+
+Signing requirements:
+- **SSH signing (preferred):** `git config --global gpg.format ssh` + `user.signingkey` pointing at your public key.
+- **GPG:** any registered GPG key works.
+- Run `git config --global user.signingkey` to confirm a key is configured.
+
+Confirm the tag actually carries a signature (this is what CI checks):
+
+```bash
+git cat-file -p v<NEW_VERSION> | grep -c "BEGIN SSH SIGNATURE"   # expect 1 (or "BEGIN PGP SIGNATURE" for GPG)
+```
+
+> **Benign local-verify error:** `git tag -v v<NEW_VERSION>` may fail with
+> `gpg.ssh.allowedSignersFile needs to be configured`. This is a *local
+> verification-config* gap only — the tag IS validly signed and CI still passes
+> (CI greps for the signature header, above). To make local verify work once and
+> for all, create an allowed-signers file (`<your-email> ssh-rsa AAAA...`) and run
+> `git config --global gpg.ssh.allowedSignersFile <path>`. See the `release-signing`
+> memory for the exact recipe. Do NOT treat this error as a signing failure.
+
+**13. Push the tag first** (bypasses branch protection; triggers the CI release workflow immediately):
+
+> **⚠ POINT OF NO RETURN — confirm with the user before this push.** Pushing the
+> tag immediately triggers `.github/workflows/release.yml` → **PyPI publish +
+> public GitHub Release**. A pushed release tag must NOT be force-replaced (ship a
+> PATCH instead). Get an explicit go-ahead, then push.
+
+```bash
+git push origin v<NEW_VERSION>
+```
+
+CI will start building the release. Watch <https://github.com/ffroliva/gflow-cli/actions>.
+Wait for the `Release` run to report **completed / success** and confirm the GitHub
+Release published before continuing (`gh release view v<NEW_VERSION>`).
+
+**14. Push the release branch and open the PR.**
+
+```bash
+git push -u origin chore/release-v<NEW_VERSION>
+gh pr create --base main --head chore/release-v<NEW_VERSION> \
+  --title "chore(release): v<NEW_VERSION>"
+```
+
+Wait for PR CI to go green (`gh pr checks <N> --watch`), then merge with a **merge
+commit** — never squash:
+
+```bash
+gh pr merge <N> --merge --delete-branch
+```
+
+> **NEVER `--squash` this PR.** Because the branch was cut from `develop`, the PR
+> carries the entire batch of unreleased integration commits. A squash collapses
+> them into one opaque commit on `main` and destroys that history. `--merge`
+> preserves it. (The release workflow already ran from the tag push in step 13 —
+> this PR is to bring the bump commit + integration history onto `main`.)
+
+**15. Back-merge `main` into `develop`.**
+
+After the release PR is merged, bring the bump commit back to `develop` so branches stay aligned:
+
+```bash
+git checkout develop
+git pull origin develop
+git fetch origin main
+git merge origin/main --no-ff -m "chore: back-merge main (v<NEW_VERSION>) into develop"
+git push origin develop
+```
+
+If there are conflicts (rare — only if `develop` has commits that touched the same lines as the bump), resolve them, keeping `develop`'s unreleased work and `main`'s version bump.
+
+**16. Report.**
+
+Tell the user:
+- Tag push triggered `.github/workflows/release.yml`.
+- Watch <https://github.com/ffroliva/gflow-cli/actions> for the release workflow.
+- On success: PyPI publish + GitHub Release with auto-generated notes.
+- On failure (most common: PyPI Trusted Publishing not yet configured): point to <https://pypi.org/manage/account/publishing/>.
+- `develop` is now synced with `main` (back-merge done in step 15).
+- Next development cycle starts on `develop` — open `## [Unreleased]` in CHANGELOG is ready.
+
+---
+
+## Critical reminders
+
+- **ALWAYS** cut the release branch from `develop`, not `main` — `develop` carries the work.
+- **NEVER** `--squash` the release PR into `main` — it destroys the integration history the branch carries. Use `--merge`.
+- **NEVER** skip the `main → develop` back-merge (step 15) — skipping it guarantees conflicts at the next release.
+- **NEVER** add `Co-Authored-By: Claude` (or any AI co-author) to the release commit.
+- **NEVER** force-push a release tag once it's on GitHub. Ship a PATCH fix instead.
+- **NEVER** `--no-verify` past hooks. Fix the underlying issue.
+- **NEVER** push directly to `main` — branch protection will reject it. Always use a PR.
+- A `git tag -v` `allowedSignersFile` error is **benign** (verify-only) — the tag is still signed and CI passes. Don't treat it as a failure.
+- **CONFIRM with the user before the step 13 tag push** — it's the irreversible PyPI + public Release trigger.
+- If quality gates fail at step 4, **STOP**. Surface the failures to the user.
+- If doc-review fails at step 10, **STOP**. Fix before committing.
+
+---
+
+## See also
+
+- [RELEASE.md](../../../RELEASE.md) — full release protocol, prerelease policy, and checklist
+- [README § Releases](../../../README.md#releases) — release policy and cadence
+- [PLAN § Phase 5](../../../PLAN.md#phase-5--public-alpha-release-on-pypi) — first-release exit criteria

gflow_cli-0.12.0/.claude/commands/gflow/status.md

@@ -0,0 +1,12 @@
+---
+description: Show current plan state — active plan file, goal, progress, and next unchecked task.
+---
+
+# `/gflow:status [feature]` — Current plan state
+
+**Read `skills/status/SKILL.md` and follow the `status` variant protocol**, passing `$ARGUMENTS` as the optional feature slug.
+
+> Do **not** call `Skill(skill="status")` — read the file directly.
+
+The skill at `skills/status/SKILL.md` runs `scripts/dev/active_plan.py` and returns
+the full output: plan file path, title, goal, progress (X/N), and next task block.

{gflow_cli-0.10.0 → gflow_cli-0.12.0}/.gitignore

@@ -63,6 +63,9 @@ samples/*.captured.json # sandbox-recorded API exchanges may contain PII
 test_assets/smoke_*/
 test_assets/debug_*/
 
+# Phase-2 live-spike capture outputs — NEVER commit (may contain real API payloads)
+scripts/dev/_spike_out/
+
 # Live Flow traffic captures — NEVER commit (contain real Bearer tokens / API keys).
 # Diagnostic scripts MUST default-write here, NOT to samples/captured/.
 # Sanitised reference samples (no secrets) can still live under samples/captured/.
@@ -83,3 +86,6 @@ worktrees/
 
 # E2E test logs (live Flow runs — may contain account/profile names)
 .planning/e2e-logs/
+
+# Understand Anything (local knowledge graph)
+.understand-anything/

gflow_cli-0.12.0/.planning/issue-125-fix.md

@@ -0,0 +1,207 @@
+# Issue #125 fix plan — `gflow video i2v` silently routes to T2V with `omni-flash`
+
+**Branch:** `bugfix/issue-125-i2v-t2v` (worktree at `.claude/worktrees/bugfix+issue-125-i2v-t2v/`)
+**Issue:** https://github.com/ffroliva/gflow-cli/issues/125
+**Status:** Plan — awaiting 5-persona council review before implementation.
+
+---
+
+## 1. Root cause (confirmed at zero credit)
+
+`omni-flash` does NOT support i2v interpolation (start+end frames). Flow's frontend silently drops the bound mediaIds at submit time and routes the request to `batchAsyncGenerateVideoText` with `image_inputs: null`. The user is charged 1 credit for a pure text-to-video generation that ignores the start/end frames entirely.
+
+This is **NOT** the originally hypothesised selector / UI-path bug. The "Add to Prompt" click in `_upload_via_open_dialog` IS correct on both EN and pt-BR locales (probe v1). The frame slots transition correctly (`FRAME_SLOTS_STRUCT.count()` drops 2 → 1 → 0, probe v3). The submit-button selector finds the right "Criar" button (probe v3). The bug is at Flow's model-vs-request-shape compatibility check, which is invisible from the DOM.
+
+## 2. Evidence
+
+### Zero-credit evidence
+
+| Probe | Sequence | Model | Captured URL | startImage | endImage |
+|---|---|---|---|---|---|
+| v4 prod-order | attaches → prompt → submit | (inherits Flow's last = omni-flash) | `batchAsyncGenerateVideoText` ❌ | `null` | `null` |
+| v4 reorder | prompt → attaches → submit | omni-flash | `batchAsyncGenerateVideoText` ❌ | `null` | `null` |
+| **v5 omni-flash + start+end** | attaches → prompt → submit | omni-flash (explicit) | `batchAsyncGenerateVideoText` ❌ | `null` | `null` |
+| **v5 omni-flash + start-only** | Start only → prompt → submit | omni-flash (explicit) | `batchAsyncGenerateVideoText` ❌ | `null` | `null` |
+| **v5 veo-lite + start+end** | attaches → prompt → submit | **veo-lite** | **`batchAsyncGenerateVideoStartAndEndImage` ✓** | **`4e551690...` ✓** | **`700c5522...` ✓** |
+
+**Conclusion: omni-flash does NOT support i2v in ANY form** — neither start-only nor start+end. The strict rejection in §3 is verified, not just conservative.
+
+Output dirs:
+- `C:\Users\ffrol\gflow-output\i2v-intercept-prodorder-20260530-160535\evidence.json` (omni-flash, broken)
+- `C:\Users\ffrol\gflow-output\i2v-intercept-veolite-20260530-165432\evidence.json` (veo-lite, correct)
+
+### Human-session HAR evidence
+
+`C:\Users\ffrol\Downloads\labs.google14.har` — manual i2v session on the same account, same UI flow as gflow. The captured generate body shows:
+
+```json
+{
+  "videoModelKey": "veo_3_1_interpolation_lite",  // ← Flow auto-promotes veo_3_1_lite → veo_3_1_interpolation_lite when start+end frames are present
+  "startImage": { "mediaId": "3c65f7ed-..." },
+  "endImage":   { "mediaId": "7e70fd03-..." }
+}
+```
+
+### Paid run evidence
+
+The original gflow paid retry (`C:\Users\ffrol\gflow-output\i2v-prompt-retry-20260530-133705\_err2.log`) used `--model omni-flash` (gflow's default), produced an 8s "wake-up in bedroom" stickman video that has zero visual continuity with `01-t2i.jpg` (stickman at desk) or `02-i2i.jpg` (arms-raised triumph at sunrise). Per the structured-log `generate_captured` event, the request URL was `batchAsyncGenerateVideoText` with all-null image_inputs — pure T2V from the prompt alone.
+
+**Retroactive impact:** every i2v paid run on `gflow v0.10.0` with the default model (or `--model omni-flash`) has been a silent T2V. The wf-004 promo "drift" was not Veo style-shift — it was a pure T2V.
+
+## 3. Scope
+
+### In scope (this PR) — council-revised
+
+- Add model-vs-mode compatibility helper `VideoModel.supports_i2v_interpolation()` returning False for `OMNI_FLASH`, True for the four `VEO_3_1_*` variants. Add `I2V_DEFAULT_MODEL = VideoModel.VEO_3_1_LITE` module constant in `api/video.py` (domain).
+- **Typed error class** `ModelModeIncompatibilityError` (new, in `gflow_cli.errors`) wired into `EXIT_CODE_MAP` with **exit code 17** (distinct from Click's exit 2 "usage error" and generic exit 1). Per CLI UX council finding: "semantic model/mode incompatibility known to the domain deserves a typed error."
+- `gflow video i2v` CLI: drop `omni-flash` from the i2v command's `--model` Click `Choice` tuple entirely (cleanest UX per CLI UX council). The `--help` output then lists only valid models; users see the constraint at help time. Note: t2v / r2v keep `omni-flash` in their Choice.
+- `gflow video i2v` CLI: when `--model` omitted → resolve to `I2V_DEFAULT_MODEL` (`veo-lite`). When a deserialized config still names `omni-flash` (e.g. from a stale `--config` JSON), the Click callback raises `ModelModeIncompatibilityError`.
+- **Defense-in-depth transport guard** in `_generate_video_locked`: place **immediately after `_select_video_model` (~L1170)** and BEFORE any `_attach_frame` call (Architect + Performance both flagged this as the right placement — fails before any DOM mutation, no cleanup needed, no `page.reload()`). Guard checks `mode is Mode.I2V and (start_image is not None or end_image is not None) and not model.supports_i2v_interpolation()` → raises `ModelModeIncompatibilityError`. Catches direct `FlowApiClient` callers (gflow-cli-remotion) who bypass Click.
+- **Structlog event** `ui_automation_video.model_mode_rejected` emitted by the transport guard before raising — fields `{model, mode, has_start_image, has_end_image, issue_ref: "#125"}`. Required for e2e assertion per CLI UX council + [[verification-ledger-5-layer]].
+- `--model` Click `help=` text on i2v + i2v command `examples=` corrected.
+- Unit tests for the typed error, Choice-drop, default resolution, transport guard, and structlog assertion — see §6.
+- CHANGELOG entries under both `### Fixed` and `### Changed` (the default-model shift is a Changed behaviour worth surfacing separately).
+- Update issue #125 with the actual root cause and link the PR.
+- Ship two diagnostic probes (`capture_i2v_post_bind_state.py`, `capture_i2v_intercept_submit.py`). **DROP probe v1 (`capture_i2v_upload_dialog_dom.py`)** — it proved a refuted hypothesis; ship-as-doc was post-hoc justification per Devil's Advocate.
+
+### Out of scope (deferred — with evidence-based plan)
+
+- **r2v + omni-flash compatibility** — Devil's Advocate flagged for in-scope inclusion. Probing r2v requires extending the probe with `--mode references` (different sub-mode, different attach helper `_attach_references`, different endpoint family `batchAsyncGenerateVideoReferenceImages`). Material rewrite. **Decision: file follow-up issue with a one-line probe extension as the first task. Defer scope expansion until evidence in hand.** The plan's transport guard is structured so adding r2v rejection later is a one-line change (`mode is Mode.R2V and not model.supports_r2v(...)`).
+- **omni-flash + start-only i2v** — RESOLVED by probe v5: also routes T2V. Already covered by the in-scope reject-omni-flash-for-any-i2v rule. No longer "unverified strictness."
+- **Full model+mode compatibility matrix** — broader spec; separate work.
+- **Selector-cascade hardening for `_upload_via_open_dialog`** (originally Stage A from the predict review) — no longer needed; probe v1 confirmed the selector works on pt-BR. Drop this scope. (Probe itself dropped from ship list per above.)
+
+## 4. Files touched — council-revised
+
+| File | Purpose | Change |
+|---|---|---|
+| `src/gflow_cli/api/video.py` | Domain | Add `VideoModel.supports_i2v_interpolation()` classmethod. Add `I2V_DEFAULT_MODEL = VideoModel.VEO_3_1_LITE`. Per Architect: "domain invariant, not adapter knowledge — analogous to `Aspect.wire()`." |
+| `src/gflow_cli/errors.py` | Typed error | Add `ModelModeIncompatibilityError(GFlowError)` with `exit_code=17`. Per CLI UX council. |
+| `src/gflow_cli/cli_video.py` | CLI surface | Drop `omni-flash` from i2v `--model` Click `Choice` (cleanest discoverability per CLI UX). Add a Click callback resolving omitted `--model` to `I2V_DEFAULT_MODEL`. Raise `ModelModeIncompatibilityError` if a deserialized config still names `omni-flash` for i2v. Update i2v `--model help=` and command examples. |
+| `src/gflow_cli/api/transports/ui_automation_video.py` | Transport guard | In `_generate_video_locked`, **immediately after `_select_video_model` (~L1170), BEFORE `_attach_frame`**: emit `ui_automation_video.model_mode_rejected` event and raise `ModelModeIncompatibilityError` if `mode is Mode.I2V and (start_image is not None or end_image is not None) and not model.supports_i2v_interpolation()`. Per Architect + Performance: earlier placement = no DOM mutation, no cleanup needed. **No `page.reload()`** — drop the R6 mitigation entirely. |
+| `tests/api/test_video.py` (or sibling) | Unit | `test_supports_i2v_interpolation_matrix` parametrized over all 5 VideoModel variants. `test_i2v_default_model_is_veo_lite`. |
+| `tests/errors/test_exit_codes.py` (or sibling) | Unit | `test_model_mode_incompatibility_error_exit_code_17` + ordering-invariant. |
+| `tests/cli/test_cli_video.py` (or sibling) | Unit | i2v --help no longer lists omni-flash; omitted --model resolves to veo-lite; explicit omni-flash via stale config raises exit 17. |
+| `tests/api/transports/test_ui_automation_video.py` (or sibling) | Unit | `test_transport_rejects_i2v_with_omni_flash` — stubbed request DTO, assert raise + `model_mode_rejected` event captured. |
+| `CHANGELOG.md` | Release note | New `### Fixed` entry (i2v silent T2V regression) + new `### Changed` entry (i2v default model shift to veo-lite). |
+| `scripts/dev/capture_i2v_post_bind_state.py` | Dev tooling | NEW — slot-state regression probe. |
+| `scripts/dev/capture_i2v_intercept_submit.py` | Dev tooling | NEW — definitive zero-credit reproducer (the smoking-gun probe). |
+| ~~`scripts/dev/capture_i2v_upload_dialog_dom.py`~~ | ~~Dev tooling~~ | **DROPPED from ship list** — proved a refuted hypothesis; not maintaining as documentation. |
+
+## 5. Implementation steps (in order — each a focused commit) — council-revised
+
+1. **Add `ModelModeIncompatibilityError`** to `gflow_cli.errors` + wire into `EXIT_CODE_MAP` with `exit_code=17`. Unit test for ordering-invariant + the new mapping.
+2. **Add `VideoModel.supports_i2v_interpolation()` + `I2V_DEFAULT_MODEL`** in `api/video.py` + unit tests.
+3. **Drop omni-flash from i2v's `--model` Click `Choice`; add resolution callback** in `cli_video.py`. Add `ModelModeIncompatibilityError` raise for the stale-config edge case. Unit tests for both paths.
+4. **Transport guard** at the correct placement (just after `_select_video_model`) in `_generate_video_locked` + structlog event + unit test stubbing the request DTO. Verify no `page.reload()` is added.
+5. **Update `--model help=` text + i2v command examples** in `cli_video.py`.
+6. **CHANGELOG**: `### Fixed` + `### Changed` entries.
+7. **Add the two dev probes** to `scripts/dev/`: `capture_i2v_post_bind_state.py` + `capture_i2v_intercept_submit.py`. Do NOT add `capture_i2v_upload_dialog_dom.py`.
+8. **Update issue #125** with the corrected root cause and link to the PR (in §7 verification, after merge).
+
+## 6. Test plan — council-revised
+
+### Unit tests
+
+- `test_omni_flash_does_not_support_i2v_interpolation`: `VideoModel.OMNI_FLASH.supports_i2v_interpolation() is False`
+- `test_veo_3_1_models_support_i2v_interpolation`: parametrize across the four VEO_3_1_* variants, all return True
+- `test_i2v_default_model_constant`: `I2V_DEFAULT_MODEL is VideoModel.VEO_3_1_LITE`
+- `test_model_mode_incompatibility_error_exit_code_is_17`: `ModelModeIncompatibilityError().exit_code == 17` and the class is registered in `EXIT_CODE_MAP`
+- `test_exit_code_map_ordering_invariant_still_holds` after the new entry (per [[exit-code-map-ordering-invariant-test-pitfall]])
+- `test_i2v_click_choice_excludes_omni_flash`: introspect the i2v command's `--model` Click `Choice` — `"omni-flash" not in choices`. (Compare to t2v Choice which DOES include it.)
+- `test_i2v_cli_resolves_default_to_veo_lite`: `gflow video i2v start.jpg "p" --end-image end.jpg` (no --model) → resolved model in the request DTO is `VideoModel.VEO_3_1_LITE`
+- `test_i2v_cli_rejects_stale_config_with_omni_flash`: a deserialized config JSON pointing at omni-flash for i2v → exits **17** (not 2) with stderr containing "#125" and "veo-lite"
+- `test_transport_raises_on_i2v_with_omni_flash_and_end_image`: invoke `_generate_video_locked` with a stubbed request `(model=OMNI_FLASH, mode=I2V, start_image=Path, end_image=Path)` → raises `ModelModeIncompatibilityError`, structlog captures `model_mode_rejected` event with fields `{model: "omni_flash", mode: "I2V", has_start_image: True, has_end_image: True, issue_ref: "#125"}`. **No DOM mutation must have occurred** — assert no `_attach_frame` call fired (via mock).
+- `test_transport_raises_on_i2v_with_omni_flash_and_start_only`: same shape but `end_image=None`, `start_image=Path` — still raises (omni-flash rejected for any i2v ref, per probe evidence).
+- `test_transport_does_NOT_raise_on_t2v_with_omni_flash`: pure t2v + omni-flash is a valid combination — guard must NOT fire.
+
+### Integration tests
+
+- BDD scenario: "user runs i2v with default model" → command resolves to veo-lite, no Flow interaction. Assert `structlog` shows `model_mode_rejected` is NOT emitted.
+- BDD scenario: "in-process API caller (e.g. flow_workflow.py shape) passes `model=OMNI_FLASH, mode=I2V, start_image=Path` to `FlowApiClient.generate_video`" → raises `ModelModeIncompatibilityError`, exit code 17. **This is the safety net for gflow-cli-remotion-style consumers.**
+- Audit existing i2v integration tests: any fixture using omni-flash for i2v must be updated to a Veo 3.1 model.
+
+### Live e2e (1 paid credit)
+
+- Re-run probe v5 (`capture_i2v_intercept_submit.py --model veo-lite ...`) zero-credit sanity check — captured URL must still be `StartAndEndImage` with bound mediaIds.
+- Then a live `gflow video i2v 01-t2i.jpg "<tightened stickman motion prompt>" --end-image 02-i2i.jpg --model veo-lite --aspect 9:16 --profile promo-denon82` → expect:
+  - structured log `ui_automation_video.generate_captured` event with `url=batchAsyncGenerateVideoStartAndEndImage` and `image_inputs.startImage` + `image_inputs.endImage` non-null
+  - **assert structured log does NOT contain `ui_automation_video.model_mode_rejected`** (positive verification that the new guard didn't false-fire on a valid combination)
+  - output mp4 visually: 2D ink line-art stickman starting at desk (matches 01-t2i.jpg), interpolating to arms-raised at sunrise (matches 02-i2i.jpg)
+  - 5-layer verification ledger per memory [[verification-ledger-5-layer]]: file count, magic bytes (mp4 signature), Pillow dims (720×1280), structlog invariants (above), user gallery confirmation.
+
+## 7. Verification ladder (definition of done) — council-revised
+
+- [ ] `ruff format --check` + `ruff check` clean on `src/gflow_cli/{cli_video,errors,api/video,api/transports/ui_automation_video}.py` and the two dev probe scripts shipping.
+- [ ] `pyright` clean on the same scoped paths.
+- [ ] All new unit tests pass (see §6).
+- [ ] Scoped pytest of `tests/cli/` + `tests/api/` + `tests/api/transports/` + `tests/errors/` passes (full sweep deferred to CI per [[full-test-suite-ooms]]).
+- [ ] BDD/integration tests pass.
+- [ ] **Exit-code-map ordering-invariant test passes** (per [[exit-code-map-ordering-invariant-test-pitfall]]) — adding code 17 must not invert any prior subclass-relation invariant.
+- [ ] Probe v5 re-run with `--model veo-lite` still produces `StartAndEndImage` URL with bound mediaIds (zero credit).
+- [ ] Probe v5 re-run with `--model omni-flash --start-only` still produces T2V (zero credit — proves the rejection is still warranted).
+- [ ] 1 paid live e2e i2v run completes; structured log shows `generate_captured.url=batchAsyncGenerateVideoStartAndEndImage` with non-null mediaIds AND `model_mode_rejected` event is NOT emitted.
+- [ ] User watches the output mp4 and verbally confirms it's a 2D ink line-art stickman desk → sunrise scene matching the refs.
+- [ ] Issue #125 comment thread updated with the actual root cause + closed by PR merge.
+- [ ] CHANGELOG entries present under `[Unreleased]` — both `### Fixed` and `### Changed`.
+
+## 8. Risks + mitigations
+
+| Risk | Severity | Mitigation |
+|---|---|---|
+| R1: Changing default model silently surprises users who already had a working incantation | LOW — prior incantation was broken (T2V output); making it work correctly is a strict improvement | None needed beyond clear CHANGELOG note |
+| R2: veo-lite has different cost/quality than omni-flash | LOW — both are tier-one lite models; veo-3.1-lite cost is documented in Flow's UI per `MEDIA_GENERATION_PAYGATE_TIER: PAYGATE_TIER_ONE` | Document in --model help text |
+| R3: omni-flash + start-only i2v might actually work (unverified) | MEDIUM — if it does work, our strict rejection blocks a valid combination | Conservative reject in this PR; reverse with probe evidence in a follow-up if proven |
+| R4: r2v + omni-flash has the same silent-drop pathology | MEDIUM — separate UI surface, separate ticket needed | Out of scope; file follow-up issue with link from #125 |
+| R5: Hidden in-process API callers (scripts using `FlowApiClient` directly like `gflow-cli-remotion/flow_workflow.py`) bypass the CLI validation | MEDIUM | The transport guard in `_generate_video_locked` is the safety net for these callers |
+| ~~R6: pre-submit guard raises but the page is left in a dirty state for the pool~~ | ~~LOW~~ | **DROPPED per Performance council review.** Guard now placed at L1170 (immediately after `_select_video_model`, BEFORE any `_attach_frame`) — fires before any DOM-state mutation, no Page cleanup needed, no `page.reload()`. Architect concurred ("earlier-fail is cleaner than dirty-state cleanup"). |
+
+## 9. Rollback
+
+- Revert the PR as a single commit-range. No DB migrations, no settings changes, no state mutations.
+- The transport guard fails-closed: if a user with cached venv hits the guard on a stale config, they get a clear error pointing at #125 with remediation. No silent regression.
+
+## 10. CHANGELOG entries — council-revised (two sections)
+
+```markdown
+### Fixed
+
+- `gflow video i2v` silently routed every call to the T2V endpoint with
+  `image_inputs: null` when the model was `omni-flash` (Flow's last-used
+  default in most sessions). Flow's frontend rejects omni-flash + frame
+  refs and falls back to text-only generation, but the rejection is
+  invisible to the client — every i2v paid run on v0.10.0 burned a
+  credit for a pure text-to-video generation that ignored the supplied
+  start/end frames. Issue #125. Fix: omni-flash dropped from the i2v
+  `--model` Click `Choice` entirely; a defense-in-depth transport guard
+  in `_generate_video_locked` raises `ModelModeIncompatibilityError`
+  (exit code 17) for direct `FlowApiClient` callers that bypass the CLI.
+
+### Changed
+
+- `gflow video i2v` default model is now `veo-lite` (was: inherit
+  Flow's last-used, which was typically `omni-flash` — see Fixed). The
+  veo-3.1 family is the only model line that supports i2v
+  interpolation; omni-flash is now correctly rejected for any i2v
+  invocation (start-only or start+end). Explicit `--model omni-flash`
+  for `gflow video t2v` and `gflow video r2v` remains valid.
+```
+
+## 11. Migration / backward compat
+
+- No breaking config or env-var changes.
+- v0.10.0 users running `gflow video i2v ... --end-image ...` without explicit `--model` previously got silent T2V output; they now get correct interpolation (silent improvement, no surprise).
+- v0.10.0 users running `gflow video i2v ... --end-image ... --model omni-flash` previously got silent T2V; they now get a clear error with `gflow video i2v ... --end-image ... --model veo-lite` as the remediation.
+- BREAKING for: nobody. The prior behavior was a silent bug.
+
+---
+
+## Appendix: probe scripts
+
+All zero-credit. Only two ship in this PR per Devil's Advocate review (probe v1 dropped — proved a refuted hypothesis, no future-locale-regression value).
+
+| Probe | What it proved | Ships? |
+|---|---|---|
+| `capture_i2v_upload_dialog_dom.py` | "Incluir no comando" pt-BR button matches the production `add_btn` selector — selector cascade is correct (REFUTED original hypothesis). | **NO** — proved a refuted hypothesis; not maintaining as documentation. |
+| `capture_i2v_post_bind_state.py` | `FRAME_SLOTS_STRUCT.count()` transitions 2 → 1 → 0 after binds; submit button is unambiguous (single arrow_forward "Criar" button); slots stay bound after prompt typing. | **YES** — useful future probe for slot-state regressions. |
+| `capture_i2v_intercept_submit.py` | Intercepts the submit XHR via `page.route(..., abort)` and inspects the request body. omni-flash → T2V with null images (both start+end and start-only); veo-lite → StartAndEndImage with populated mediaIds. **This is the definitive reproducer.** | **YES** — definitive regression probe for future model/mode work. |

{gflow_cli-0.10.0 → gflow_cli-0.12.0}/AGENTS.md

@@ -8,7 +8,8 @@ Supported tools that auto-discover this file: Cursor, Codex, Aider, Jules, Devin
 
 - Unofficial Python CLI for [Google Flow](https://labs.google/fx/tools/flow) — drives Veo (image-to-video, text-to-video) and Imagen (text-to-image) generations from the terminal by reverse-engineering Flow's private REST API at `aisandbox-pa.googleapis.com`.
 - Python 3.11+ · `uv`-managed · `hatchling` builds · Playwright Chromium transport · `pyright` strict · `ruff` · `pytest`.
-- Single-package modular monolith. Top-level modules under `src/gflow_cli/`: `api/`, `auth/`, `browser_manager.py`, `cli.py`, `_cli_helpers.py`, `cli_data.py`, `cli_image.py`, `cli_run.py`, `cli_video.py`, `config.py`, `data/`, `errors.py`, `exceptions.py`, `image_batch.py`, `manifest.py`, `observability.py`, `paths.py`, `profile_store.py`.
+- Single-package modular monolith. Top-level modules under `src/gflow_cli/`: `api/`, `auth/`, `browser_manager.py`, `cli.py`, `_cli_helpers.py`, `cli_character.py`, `cli_data.py`, `cli_image.py`, `cli_models.py`, `cli_run.py`, `cli_scene.py`, `cli_video.py`, `config.py`, `data/`, `errors.py`, `exceptions.py`, `image_batch.py`, `manifest.py`, `observability.py`, `paths.py`, `profile_store.py`.
+- Command surface: `gflow auth`, `gflow image` (t2i/i2i/upload), `gflow video` (t2v/i2v/r2v/batch/chain), `gflow character` (create/list/show/voices — reusable project-scoped Flow Character entities), `gflow scene` (create/show — Add Clip / Scenes, with `create --output` for credit-free server-side extended video), and `gflow data` (catalog queries).
 - Requires a Google AI Ultra or Pro subscription with Flow access. All generations bill against the user's own Google account.
 
 ## Headed-browser dependency (architectural reality)
@@ -28,7 +29,7 @@ If you can help unblock a pure HTTP transport (especially for video generation,
 - Copy `.env.template` to `.env.local`; never commit `.env.local`. It documents every env var.
 - Output goes to `./tmp/` for scripts/tests or `$GFLOW_CLI_OUTPUT_DIR` for CLI outputs (defaults to `./out/`).
 - One-time auth: `gflow auth login --browser chrome`. The `--browser chrome` flag is mandatory; the CLI fails fast on other strategies.
-- Use `/gflow:plan` to see the active phase before starting work; `/gflow:known-issues` before touching auth or reCAPTCHA code paths.
+- Use `/gflow:status` to see the current task before starting work; `/gflow:known-issues` before touching auth or reCAPTCHA code paths.
 
 ## Testing instructions — The Impeccable Routine
 
@@ -55,7 +56,7 @@ Or invoke the wrapper: `/gflow:check`.
 
 - Type hints everywhere; `pyright` strict on `src/gflow_cli`.
 - Structured logging only (`structlog`) — **never** raw `print()` or `import logging` in `src/`.
-- Errors as RFC 9457 Problem Details with stable per-class exit codes (3–16, where 16 is the `DataStoreError` family from `gflow_cli.data`). See `src/gflow_cli/errors.py::EXIT_CODE_MAP` for the complete mapping.
+- Errors as RFC 9457 Problem Details with stable per-class exit codes (3–21, e.g. 16 is the `DataStoreError` family, 19 `SceneConcatError`, 20 `FrameExtractionError`, 21 `ChainPartialError`). See `src/gflow_cli/errors.py::EXIT_CODE_MAP` for the complete mapping.
 - 100-char line length, `ruff` configured. Imports sorted by `ruff` (isort rules).
 
 ## PR instructions
@@ -66,13 +67,30 @@ Or invoke the wrapper: `/gflow:check`.
 - Run `/gflow:check` (or the Impeccable Routine) before every commit.
 - All releases require a signed annotated tag (`git tag -s vX.Y.Z`); CI rejects unsigned tags.
 
+## Skills reference (cross-tool)
+
+The `skills/` directory ships installable agent skill docs in plain Markdown with YAML frontmatter. Any agent can consume them directly:
+
+| Skill | Path | When to load |
+|---|---|---|
+| `gflow-cli` | [`skills/gflow-cli/SKILL.md`](skills/gflow-cli/SKILL.md) | User wants to run any `gflow` command — auth, T2V, I2V, T2I, I2I, batch |
+| `predict` | [`skills/predict/SKILL.md`](skills/predict/SKILL.md) | Pre-implementation adversarial analysis before any high-stakes change |
+| `scenario` | [`skills/scenario/SKILL.md`](skills/scenario/SKILL.md) | Edge-case explorer after a predict GO/CAUTION |
+| `pr-council-review` | [`skills/pr-council-review/SKILL.md`](skills/pr-council-review/SKILL.md) | Multi-dimensional PR council review |
+
+**Cursor / Aider / Codex / Gemini CLI:** paste or include the relevant `SKILL.md` in your system context.
+**Claude Code:** symlink `skills/gflow-cli` to `~/.claude/skills/gflow-cli` to register the skill; the `/gflow:` slash commands (in `.claude/commands/gflow/`) are auto-discovered from the project directory.
+**Custom agents:** fetch `skills/gflow-cli/SKILL.md` into your knowledge base before answering gflow questions.
+
+The SkillOpt harness at `scripts/dev/skillopt/` measures how accurately each skill guides an agent, and supports multiple providers (Anthropic, OpenAI-compat, Gemini, local models). See [`scripts/dev/skillopt/README.md`](scripts/dev/skillopt/README.md).
+
 ## Where to look next
 
 - **Architecture & target shape** → [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
 - **Mandates & routing rules** → [docs/AGENT_GUIDE.md](docs/AGENT_GUIDE.md)
 - **Full docs index** → [docs/INDEX.md](docs/INDEX.md)
 - **Known issues** (read before touching auth / reCAPTCHA) → [KNOWN_ISSUES.md](KNOWN_ISSUES.md)
-- **Active phase & backlog** → [PLAN.md](PLAN.md) or run `/gflow:plan`
+- **Current task** → `/gflow:status` · **Create a feature plan** → `/gflow:plan <feature>` · **Full roadmap** → [PLAN.md](PLAN.md)
 - **Release protocol** → [RELEASE.md](RELEASE.md)
 
 ## Claude Code-specific notes