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

{gflow_cli-0.12.0 → gflow_cli-0.14.0}/.github/workflows/ci.yml

@@ -21,7 +21,7 @@ jobs:
           fetch-depth: 0  # full history so gitleaks can diff against base
 
       - name: Run gitleaks
-        uses: gitleaks/gitleaks-action@v2
+        uses: gitleaks/gitleaks-action@v3
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 

gflow_cli-0.14.0/.github/workflows/governance-advisory.yml

@@ -0,0 +1,33 @@
+name: Governance advisory
+
+# Non-blocking governance signal: classifies touched paths (material vs routine)
+# and surfaces a recommendation to run /gflow:predict + council review. It NEVER
+# fails the build and is NOT a required check — mirrors the reference AI-DLC
+# orchestrator's advisory-by-default risk gate. Hard enforcement (--block-on +
+# branch protection) is a conscious, documented deferral.
+
+on:
+  pull_request:
+
+# Least privilege: the script writes to $GITHUB_STEP_SUMMARY (no token needed).
+# read-only is sufficient; we do not post comments (which forks cannot do).
+permissions:
+  contents: read
+
+jobs:
+  materiality:
+    name: Materiality + traceability (advisory)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0 # full history so `git diff origin/<base>..HEAD` resolves
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Classify touched paths (advisory, never blocks)
+        run: |
+          git fetch --no-tags origin "${{ github.base_ref }}" || true
+          uv run python scripts/ci/check_materiality.py \
+            --base "origin/${{ github.base_ref }}"

gflow_cli-0.14.0/.github/workflows/governance-benchmark.yml

@@ -0,0 +1,29 @@
+name: Governance benchmark
+
+# Periodic calibration of the advisory materiality gate. Replays git history and
+# writes the false-positive / coverage report to the job summary. This is a
+# DASHBOARD, not a gate: non-blocking, read-only, no token (fork-safe). See
+# docs/GOVERNANCE_BENCHMARK.md.
+
+on:
+  schedule:
+    - cron: "0 6 1 * *" # 06:00 UTC on the 1st of each month
+  workflow_dispatch: # manual run from the Actions tab
+
+permissions:
+  contents: read
+
+jobs:
+  backtest:
+    name: Materiality gate backtest
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0 # full history — the backtest replays every commit
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Run backtest (advisory; writes to job summary)
+        run: uv run python scripts/dev/materiality_backtest.py >> "$GITHUB_STEP_SUMMARY"

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

@@ -9,7 +9,7 @@ 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_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).
+- Command surface: `gflow auth`, `gflow image` (t2i/i2i/upload), `gflow video` (t2v/i2v/r2v/batch/chain), `gflow character` (create/list/show/rm/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)

{gflow_cli-0.12.0 → gflow_cli-0.14.0}/CHANGELOG.md

@@ -7,6 +7,84 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.14.0] — 2026-06-07
+
+### Added
+
+- **`gflow movie` — multi-scene, character-consistent video generation.** A TOML
+  manifest (`gflow movie template` / `gflow movie run`) drives a sequence of clips
+  that reuse a single Flow CHARACTER entity (reference-to-video) so the same face
+  and voice carry across every scene. Generate-only by default; `--stitch`
+  produces an ffmpeg preview concat; runs are crash-resumable via the sibling
+  `<manifest>-state.json`; a versioned handoff manifest is written for downstream
+  composition (e.g. Remotion). Deterministic prompt assembly (`composition.py`),
+  scene = clip.
+- **`docs/MOVIE.md`** — manifest format, the run lifecycle (the headed browser is
+  required through generate → poll → download), the character-entity attach
+  mechanism, and the best-effort consistency model.
+- Dev utilities: `scripts/dev/make_project.py` (create a Flow project) and
+  `scripts/dev/patch_character.py` (rename / set voice + personality on an entity).
+
+### Fixed
+
+- **R2V character reuse now actually rides the wire.** The entity is attached via
+  the resource picker's **Personagens tab → right-click → "Incluir no comando"**
+  (which stages `referenceEntities`; a left-click on the Tudo tile only stages the
+  thumbnail as a `referenceImage`). The submit backstop now reads the response's
+  real `media[].mediaMetadata.requestData.videoGenerationRequestData.videoGenerationEntityInputs`
+  path instead of the request-shape `requests[].referenceEntities` — which had
+  false-rejected every successful entity generation. `omni-flash` R2V verified to
+  carry the entity.
+- Cleared pre-existing type/test debt: `pyright src` is clean again (the missing
+  `project_id` parameter was added to the `VideoCapableTransport` protocol and the
+  `_enter_editor` type stub); regenerated `uv.lock` (jsonschema dev dependency).
+
+## [0.13.0] — 2026-06-04
+
+### Added
+
+- **`gflow character rm` — delete a Character entity (#150).**
+  `gflow character rm --project <id> (--id <entityId> | --name <name>) [-y/--yes] [--json]`
+  deletes a Character via `POST flow:batchDeleteAssets` (Bearer; **FREE** — no
+  reCAPTCHA, no credit). Resolves by id or exact name (ambiguous name exits
+  **11**); prompts for confirmation unless `--yes`/`--json`.
+
+- **In-project governance enforcement (advisory-first).** Made the AI-driven
+  development flow followable and partly machine-enforced in-repo, modeled on the
+  reference AI-DLC governance orchestrator's advisory-by-default behavior:
+  ruff `T20` now bans raw `print()` in `src/`; an advisory branch-naming check and a
+  non-blocking materiality + traceability classifier (`scripts/ci/check_materiality.py`
+  + `governance-advisory.yml`) recommend `/gflow:predict` + council review when
+  sensitive paths (`auth/`, `api/transports/`, `api/client.py`, `_sapisidhash.py`,
+  `data/`, `recaptcha`) are touched, without ever blocking a merge. A
+  history-replay backtest (`scripts/dev/materiality_backtest.py`) calibrates the
+  gate — it measured a 1.1% false-positive rate (vs. a 20-30% estimate) and
+  raised fix-coverage from 61% to 74% by surfacing auth-token plumbing that lived
+  outside `auth/`. The backtest is a first-class, repeatable artifact (`--json`
+  mode, a monthly `governance-benchmark.yml` dashboard job) fully documented in
+  [`docs/GOVERNANCE_BENCHMARK.md`](docs/GOVERNANCE_BENCHMARK.md); the gate itself is
+  described in
+  [`docs/AGENT_GUIDE.md` § Governance & Enforcement](docs/AGENT_GUIDE.md#governance--enforcement).
+
+### Changed
+
+- **`gflow video i2v` frame flags aligned with Flow UI terminology (#122).**
+  `--initial-frame FILE` is the new canonical flag for the start image (matches
+  Flow's "initial frame" label). `--end-frame FILE` replaces `--end-image` as the
+  canonical end-frame flag. `--end-image` is kept as a **deprecated alias** (emits
+  `DeprecationWarning`; will be removed in a future minor release). The positional
+  `IMAGE` argument remains supported for back-compatibility.
+
+### Fixed
+
+- **Character editor 404 on non-English locales (#153).** `gflow character`'s
+  editor URL interpolated the locale verbatim, so the genuine default BCP-47
+  `en-US` produced `/fx/en-US/…`, which 404s the Flow character editor (only the
+  short primary subtag is a valid `/fx/<seg>/` segment). `character_editor_url`
+  now normalizes a BCP-47 tag to its lower-cased short segment (`en-US → en`,
+  `pt-BR → pt`), so the tool stays language-agnostic with the real default
+  locale.
+
 ## [0.12.0] — 2026-06-03
 
 ### Fixed
@@ -644,7 +722,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `gflow image batch` now actually shares one Flow project across all
   prompts in a batch. Previously the `--same-project=1` flag was a no-op
   at the `ui_automation` transport layer; each prompt landed in its own
-  Flow project. ([spec](docs/superpowers/specs/2026-05-22-stay-mounted-batch-session-design.md))
+  Flow project.
 - `gflow image t2i -n N` now makes one transport call using Flow's native
   xN count selector instead of fanning out N parallel single-image
   submissions. Closes [#14](https://github.com/ffroliva/gflow-cli/issues/14) part 1.
@@ -1356,7 +1434,9 @@ 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.12.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.14.0...HEAD
+[0.14.0]: https://github.com/ffroliva/gflow-cli/compare/v0.13.0...v0.14.0
+[0.13.0]: https://github.com/ffroliva/gflow-cli/compare/v0.12.0...v0.13.0
 [0.12.0]: https://github.com/ffroliva/gflow-cli/compare/v0.11.0...v0.12.0
 [0.11.0]: https://github.com/ffroliva/gflow-cli/compare/v0.10.0...v0.11.0
 [0.10.0]: https://github.com/ffroliva/gflow-cli/compare/v0.9.1...v0.10.0

{gflow_cli-0.12.0 → gflow_cli-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.12.0
+Version: 0.14.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
@@ -53,7 +53,7 @@ Requires-Dist: numpy>=1.24; extra == 'dev'
 Requires-Dist: pyright>=1.1.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
 Requires-Dist: pytest>=8.0.0; extra == 'dev'
-Requires-Dist: ruff>=0.5.0; extra == 'dev'
+Requires-Dist: ruff>=0.15.15; extra == 'dev'
 Provides-Extra: gcs
 Requires-Dist: gcsfs>=2024.2.0; extra == 'gcs'
 Requires-Dist: universal-pathlib>=0.2.5; extra == 'gcs'
@@ -81,6 +81,7 @@ Description-Content-Type: text/markdown
 >
 > 🌐 **Headed-browser today.** gflow drives Flow via a persistent Playwright Chromium profile — Google's auth + reCAPTCHA gates currently require it. See [Architecture & current limitations](#architecture--current-limitations) for the contributor opportunity.
 
+
 ## Why gflow-cli?
 
 For Google AI Ultra / Pro subscribers with Veo credits and batch workloads:
@@ -141,10 +142,11 @@ Reproduce the recording: [`scripts/record_demo.ps1`](scripts/record_demo.ps1) (W
 | **Storage & catalog** | [External Storage](docs/EXTERNAL_STORAGE.md) · [Data Layer](docs/DATA_LAYER.md) |
 | 🎭 **Characters** | [Characters](docs/CHARACTER.md) — reusable subjects (`gflow character`) |
 | 🔐 **Auth & sessions** | [Authentication](docs/AUTHENTICATION.md) · [Known issues](KNOWN_ISSUES.md) |
-| 🏗️ **Internals** | [Architecture](docs/ARCHITECTURE.md) · [Security](docs/SECURITY.md) · [Debugging](docs/DEBUGGING.md) |
+| 🏗️ **Internals** | [Architecture](docs/ARCHITECTURE.md) · [Security](docs/SECURITY.md) · [Debugging](docs/DEBUGGING.md) |  
 | 📦 **Releases** | [Changelog](CHANGELOG.md) · [Roadmap](ROADMAP.md) · [Release protocol](RELEASE.md) · [Project status](docs/PROJECT_STATUS.md) |
 | 🤝 **Contributing** | [Contributing](CONTRIBUTING.md) · [Development](docs/DEVELOPMENT.md) · [GitHub workflow](docs/GITHUB.md) |
 
+
 ## For AI agents & LLMs
 
 gflow-cli ships three agent entry points — pick the one your tool reads first.

gflow_cli-0.14.0/PR162_MOVIE_CHARACTER_REVIEW.md

@@ -0,0 +1,137 @@
+# PR #162 Review — Movie Orchestration Character Consistency
+
+**Branch:** `pr162` · **Scope:** `gflow movie` orchestrator (`cli_movie.py`, `movie_manifest.py`) + video transport
+**Verdict:** Sound foundation, correct project consolidation, but the headline goal (consistent character) is **not achievable with the current r2v-by-uploaded-image approach** — and there is a **release-blocking `NameError` that aborts every multi-scene run after scene 1.**
+
+---
+
+## TL;DR
+
+| # | Objective | Finding |
+|---|-----------|---------|
+| 0 | *(not in brief)* | 🔴 **CRITICAL** — `asyncio.sleep(5)` at `cli_movie.py:344` with **no `import asyncio`** → `NameError` on the 2nd scene of every movie, outside the try/except → whole run aborts after 1 scene. |
+| 1 | Native character integration | ✅ **Feasible & protocol-ready.** Flow's wire has a native field `referenceEntities:[{entityId}]` on `video:batchAsyncGenerateVideoReferenceImages` (live-verified, `docs/CHARACTER.md §6.6/§8`). The entity_id is *already saved* in state but never used. Needs a new transport path (composer resource-picker → "Personagens") + DTO field. |
+| 2 | r2v vs i2v / chain | ✅ The chaining engine **already exists** (`chain.py`, `media.extract_last_frame`, `gflow video chain`). It's just not wired into `movie.toml`. r2v+entity = identity; i2v-chain = motion continuity; **mutually exclusive per generation** (DTO enforces frames XOR references). |
+| 3 | Project consolidation | ✅ **Correct and it's the enabler.** `manifest.project` is threaded to character-create *and* every scene; `_enter_editor` deep-links to that project. This is exactly the precondition that makes native `referenceEntities` selection possible. |
+| 4 | Error handling (`generate_resp`/403) | ✅ **Already fixed.** `generate_resp={}` bound before `try` (`:1421`); 403→`WafRejectionError`, silent→`TimeoutError`; listeners freed in `finally`. No UnboundLocal remains. |
+
+---
+
+## 0. 🔴 CRITICAL — `asyncio` is not imported (multi-scene runs crash)
+
+`cli_movie.py:342-345`:
+
+```python
+# reCAPTCHA cooldown
+if completed_scene_ids:
+    await asyncio.sleep(5)      # NameError: name 'asyncio' is not defined
+```
+
+- `asyncio` appears **exactly once** in the file (the usage); it is **not** in the import block (`:17-44`).
+- `completed_scene_ids` is non-empty from the 2nd scene onward (appended at `:373`, and on resume at `:332`).
+- The call sits **outside** the per-scene `try/except` (`try` starts at `:346`), so the `NameError` propagates out of `_run_movie` → caught by `run_with_handlers` → **the entire movie aborts after exactly one scene**, regardless of `--continue-on-error`.
+- On *resume* it's worse: the first already-completed scene appends to `completed_scene_ids`, so the very first new scene hits the cooldown and crashes → **resume can make zero forward progress.**
+
+**Why it escaped CI:** the only async-orchestrator test (`tests/cli/test_cli_movie.py:368 test_happy_path_no_characters`) uses a **single** scene. No test drives `_run_movie` with ≥2 scenes, so the cooldown branch is never executed. (The `out/stickman-v3/` artifacts predate this regression — file mtime is later than the renders.)
+
+**Fix (one line):** add `import asyncio` to the import block. **Then add a 2-scene orchestrator test** so this can't regress (see §6).
+
+---
+
+## 1. Native character integration — the real fix for divergence
+
+### Current behaviour (confirms the brief)
+- `character_create` downloads face/body to **local disk**; `CharacterState` stores both `entity_id` *and* `image_paths` (`cli_movie.py:454-457`).
+- `_collect_refs` (`cli_movie.py:470-483`) returns **only `image_paths`** for r2v. `entity_id` is captured and then ignored.
+- `_generate_scene` passes those local paths as `reference_images`; the transport's `_attach_references` (`ui_automation_video.py:1092`) **re-uploads each file** via the "Add Media" dialog → fresh media IDs every scene → Flow sees unrelated assets → the Stickman drifts. **Exactly the diagnosed flaw.**
+
+### The native path exists and is verified
+From `docs/CHARACTER.md §6.6` (live-verified 2026-06-02, `labs.google23.har`):
+
+```json
+"video:batchAsyncGenerateVideoReferenceImages" → {
+  "referenceImages":   [ { "mediaId", "imageUsageType":"IMAGE_USAGE_TYPE_ASSET" } ],
+  "referenceEntities": [ { "entityId" } ]      // ← native character identity
+}
+```
+
+- `referenceEntities` is a **list** → multi-character per scene (`VIDEO_MODEL_CAPABILITY_MULTI_REFERENCE`).
+- UI flow: composer → resource picker (*"Pesquisar recursos"*) → **Personagens** tab → select → **"Incluir no comando"** → injects `referenceEntities`.
+- CLI `gflow video … --character <id>` is documented **backlog Phase 3 — unimplemented** (`docs/CHARACTER.md §8`). So this is *new automation*, not a refactor of existing code.
+
+### Proposed refactor
+
+**(a) DTO** — `api/video.py`, `GenerateVideoRequest`:
+```python
+reference_entities: tuple[str, ...] = ()   # R2V — Flow CHARACTER entity ids
+```
+⚠️ Relax `__post_init__`: today R2V **requires** `reference_images` (`video.py:249-252`). Change to *require `reference_images` **or** `reference_entities`* (either anchors the clip). Keep frames XOR references.
+
+**(b) Transport** — new `_attach_character_entities(page, names, out_dir)` that, in `references` sub-mode, opens the resource picker, switches to the Characters/"Personagens" tab, selects each character **by display name**, clicks "Include in prompt". In `_generate_video_locked` R2V branch (`:1406`): if `request.reference_entities` → use entity attach; else fall back to `_attach_references`. (Both *may* coexist per the wire.)
+- **Defense-in-depth (mirror the #125 backstop):** after submit, assert the captured generate payload's `referenceEntities` contains the expected `entityId`; if it's missing, raise rather than report a false success — otherwise an entity that silently failed to attach degrades to a plain text-only clip with no warning.
+
+**(c) Orchestrator** — `_collect_refs` → return entity refs when `CharacterState.entity_id` is present, image paths only as fallback. Pass `reference_entities=(...entity_ids...)` into `GenerateVideoRequest`. Selection is **by name** (what the picker shows); `entity_id` is the verification key. No `movie.toml` change needed — `characters = ["Stickman"]` already names them; the orchestrator maps name→entity_id from state.
+
+**(d) Pre-flight guard** — before the scene loop, verify each named entity actually exists in the project (`client.get_character(entity_id=...)`). Currently `_collect_refs` silently **drops** a missing character (`log.warning` + `continue`, `:478`) → the scene generates with **no refs at all** → guaranteed divergence with no hard failure. Fail loud instead.
+
+---
+
+## 2. r2v vs i2v for journey continuity — the chain engine already exists
+
+**Key constraint:** R2V "references" and I2V "frames" are **separate, mutually-exclusive composer sub-modes** (`_switch_video_sub_mode`, `:903`) and the DTO enforces it (`video.py:245-252`). You **cannot** have character-entity identity *and* a seeded start-frame in the *same* generation.
+
+What each buys you:
+- **r2v + `referenceEntities`** → strong **identity** consistency per clip; hard cuts between scenes.
+- **i2v chain** (scene N+1 start = scene N's last frame) → **motion/visual continuity**; but link 0 has no identity anchor and identity drifts frame-to-frame.
+
+**You already have the chain machinery** — it's just not exposed in `movie.toml`:
+- `media.extract_last_frame(src, dst, *, offset_ms=0)` (`media.py:31`)
+- `chain.run_chain(...)` + `ChainLinkSpec`/`ChainLinkResult`/`FrameExtractor` protocols (`chain.py:74-185`) — record-before-extract, crash-resumable.
+- `chain_repo.ChainLinkRecorder` + migration `0005_add_chain_links.sql`.
+- `gflow video chain` (`cli_video.py:324 _run_chain`): "link 0 as T2V, every later link as I2V seeded by the previous clip's last frame."
+
+**Recommendation:** add an opt-in chain mode to `movie.toml` that routes through the existing `chain.run_chain()` rather than reimplementing it (e.g. top-level `mode = "chain"`, or scene-level `chain_from = "<previous scene title>"`). Then give honest guidance in docs:
+
+> For a **journey where the character must stay the same**, prefer **r2v + native character** on *every* scene (each clip independently anchored to the entity → best identity, accepts cuts). Use **chain** when smooth motion handoff matters more than identity, accepting drift. They can be mixed per-scene but never combined within one clip.
+
+The strongest practical journey today = r2v+entity on each scene; chaining is complementary, not a substitute, for the *consistency* goal specifically.
+
+---
+
+## 3. Project consolidation — verified, and it's load-bearing
+
+`manifest.project` (single value) is passed to `_create_character(project_id=…)` (`:309`) **and** `_generate_scene(project_id=…)` (`:356`); `_enter_editor` deep-links via `routes.project_editor_url(locale, project_id)` → `page.goto` (`ui_automation.py:815-818`); characters are created at the project's character-editor URL (`:2275`). So every character and every scene live in **one** project. ✅
+
+This is precisely why the native-character refactor (§1) works: the entity must be in the **active** project to appear in the composer's "Personagens" picker. The consolidation you added is the enabler — keep it, and add the §1(d) guard so a missing entity fails loudly instead of silently degrading.
+
+---
+
+## 4. Error handling (`generate_resp` / `responses` / 403) — already correct
+
+- `generate_resp: dict[str, Any] = {}` is bound **before** the `try` (`ui_automation_video.py:1421`) → no access-before-assignment on any failure path.
+- `_await_generate_response` raises a clear `TimeoutError` when reCAPTCHA fails *silently* (no response captured, `:1172-1179`).
+- `_parse_generate_response` maps **401→`AuthExpiredError`**, **403→`WafRejectionError`**, other non-200→`WireFormatError` (`:1245-1262`).
+- Both response listeners are removed in `finally` (`:1484-1488`); `generate_handler`/`status_handler` are bound before the `try`.
+- `responses` only appears in comments — no live variable by that name. **No remaining UnboundLocal/TypeError on the 403 path.** Nothing to fix here.
+
+---
+
+## 5. Other observations (non-blocking)
+
+- **Dry-run vs reality mismatch:** the plan prints `refs=[<names>]` (`:260`) but r2v actually consumes image *paths*; after §1 this becomes accurate again (names = entities). Minor.
+- `CharacterState`/`SceneState` are non-frozen dataclasses — intentional (mutated in place); fine.
+- Summary stitch hint uses `flow_operation_id or media_id` (`:371`) — good.
+
+## 6. Testing gap (ties to the DoD: "full e2e covering all scenarios")
+
+- No test drives `_run_movie` with **≥2 scenes** → the cooldown/`asyncio` path and the resume-append path are unexercised. Add: a 2-scene happy path (mock `_generate_scene`) that would have caught §0, and a resume test (one scene pre-completed in state).
+- Add a unit test asserting `_collect_refs` (post-refactor) returns entity ids when present, and a transport test asserting `referenceEntities` lands in the captured payload.
+- Per project DoD memory, a movie feature isn't done until a live e2e covers happy + all error/exit paths on a real project.
+
+---
+
+## Suggested sequencing
+
+1. **Hotfix now:** `import asyncio` + 2-scene orchestrator test. (Unblocks the feature as-is, even with uploaded-image refs.)
+2. **Identity fix:** DTO `reference_entities` + validation relax + transport entity-attach + payload backstop + orchestrator wiring + missing-entity guard.
+3. **Journey mode (opt-in):** wire `movie.toml` → existing `chain.run_chain()`; document the identity-vs-continuity tradeoff.

{gflow_cli-0.12.0 → gflow_cli-0.14.0}/README.md

@@ -17,6 +17,7 @@
 >
 > 🌐 **Headed-browser today.** gflow drives Flow via a persistent Playwright Chromium profile — Google's auth + reCAPTCHA gates currently require it. See [Architecture & current limitations](#architecture--current-limitations) for the contributor opportunity.
 
+
 ## Why gflow-cli?
 
 For Google AI Ultra / Pro subscribers with Veo credits and batch workloads:
@@ -77,10 +78,11 @@ Reproduce the recording: [`scripts/record_demo.ps1`](scripts/record_demo.ps1) (W
 | **Storage & catalog** | [External Storage](docs/EXTERNAL_STORAGE.md) · [Data Layer](docs/DATA_LAYER.md) |
 | 🎭 **Characters** | [Characters](docs/CHARACTER.md) — reusable subjects (`gflow character`) |
 | 🔐 **Auth & sessions** | [Authentication](docs/AUTHENTICATION.md) · [Known issues](KNOWN_ISSUES.md) |
-| 🏗️ **Internals** | [Architecture](docs/ARCHITECTURE.md) · [Security](docs/SECURITY.md) · [Debugging](docs/DEBUGGING.md) |
+| 🏗️ **Internals** | [Architecture](docs/ARCHITECTURE.md) · [Security](docs/SECURITY.md) · [Debugging](docs/DEBUGGING.md) |  
 | 📦 **Releases** | [Changelog](CHANGELOG.md) · [Roadmap](ROADMAP.md) · [Release protocol](RELEASE.md) · [Project status](docs/PROJECT_STATUS.md) |
 | 🤝 **Contributing** | [Contributing](CONTRIBUTING.md) · [Development](docs/DEVELOPMENT.md) · [GitHub workflow](docs/GITHUB.md) |
 
+
 ## For AI agents & LLMs
 
 gflow-cli ships three agent entry points — pick the one your tool reads first.

{gflow_cli-0.12.0 → gflow_cli-0.14.0}/docs/AGENT_GUIDE.md

@@ -53,6 +53,82 @@ Before merge, verify each item and record the evidence in the PR or final handof
 - **Git hygiene is clean:** branch targets `develop`, unrelated local changes are not included, commit messages contain no AI attribution, and generated artefacts stay out of git.
 - **Memory is updated:** durable project rules or operational lessons are written to agent memory before closing the work.
 
+## Governance & Enforcement
+
+gflow-cli's AI-driven development flow is **followable in-repo**: the lifecycle is
+documented here, and the rules that *can* be checked mechanically are. The model is
+**advisory-first** — cheap, deterministic rules are hard-enforced; the
+judgement-heavy gates (predict / council) are surfaced as non-blocking signals, not
+gates you can game. (Patterned on the reference AI-DLC governance orchestrator, which
+classifies-always but blocks only on an opt-in flag.)
+
+### The lifecycle
+
+```
+/gflow:predict  →  /gflow:scenario  →  /gflow:plan  →  (implement)  →
+/gflow:branch-review or /gflow:pr-council-review  →  /gflow:check  →  /gflow:release
+```
+
+Skip predict/scenario/plan for trivial fixes (< 10 lines, no boundary cross) and pure
+doc changes. Everything else: assess before you build.
+
+### What is hard-enforced vs advisory
+
+| Rule | Enforced by | Type |
+|---|---|---|
+| No `print()` in `src/` | ruff `T20` (`tests/**`, `scripts/**` exempt) | **hard** (CI lint) |
+| Doc links resolve | `scripts/ci/check_doc_links.py` | **hard** (CI) |
+| No tracked artefacts / hardcoded paths | `scripts/ci/check_repo_hygiene.py` | **hard** (CI + pre-commit) |
+| Coverage ≥ 80% | `pytest --cov-fail-under` / SonarCloud | **hard** (CI) |
+| Signed tags | release workflow | **hard** (CI) |
+| Material-path list ↔ SKILL §1 in sync | `test_material_list_sync_passes_on_real_skill` | **hard** (CI) |
+| Conventional branch prefix | `check_repo_hygiene.py::_check_branch_name` | **advisory** (warns; never blocks — platforms create `claude/*` / `dependabot/*` branches, and it no-ops in CI's detached-HEAD checkout) |
+| predict / council on material paths | `governance-advisory.yml` + `check_materiality.py` | **advisory** (recommendation in the job summary) |
+| Traceability (plan reference + tests) | `check_materiality.py` | **advisory** (report-only) |
+
+### Materiality coverage (path → recommended gate)
+
+Touching these surfaces triggers an advisory recommendation to run predict + council.
+The canonical list is `scripts/ci/check_materiality.py::MATERIAL_PATHS`; the priority
+weights live in [`skills/pr-council-review/SKILL.md`](../skills/pr-council-review/SKILL.md) §1.
+
+| Path | Why material | Recommended gate |
+|---|---|---|
+| `src/gflow_cli/auth/`, `recaptcha` | Google anti-bot / auth lifecycle | predict (security persona) + council |
+| `src/gflow_cli/api/client.py`, `_sapisidhash.py` | Auth-token plumbing (Bearer / access-token / SAPISID) outside `auth/`; surfaced as a coverage gap by `scripts/dev/materiality_backtest.py` (3 historical fixes) | predict (security persona) + council |
+| `src/gflow_cli/api/transports/` | Highest-risk transport surface; live-verify | predict + council (live-verify) |
+| `src/gflow_cli/data/` | SQLite migration / data-loss risk | predict + council (migration safety) |
+
+### Non-blocking signals
+
+The materiality and traceability surfaces are **informational only** — they never fail
+the build and are not required checks. They guide behaviour; only the hard gates above
+block a merge. Do not read the advisory job's red/green as a merge gate.
+
+### Calibrating the gate (is it worth the friction?)
+
+The material-path list is **measured, not asserted**.
+[`docs/GOVERNANCE_BENCHMARK.md`](GOVERNANCE_BENCHMARK.md) documents a history-replay
+backtest (`scripts/dev/materiality_backtest.py`) that scores the gate on two axes —
+false-positive friction and fix-coverage — and the loop for acting on the numbers.
+Current baseline: **1.1% false positives, 73.7% fix-coverage**. Re-run it before
+changing `MATERIAL_PATHS`.
+
+### Conscious deferral
+
+Hard enforcement of the material-path gate (an opt-in `--block-on=material` flag plus a
+branch-protection required check) is **deliberately deferred**, matching the reference
+implementation's opt-in design — it is a future option, not an omission. The hook point
+is reserved in `check_materiality.py` (which already classifies every change).
+
+### Satisfying a gate without Claude Code
+
+Every gate enforces a **deliverable**, not a Claude-specific command. Non-Claude agents
+(Cursor / Codex / Gemini CLI / Aider) and humans read the relevant `skills/<name>/SKILL.md`
+directly and produce the same artifact — e.g. read `skills/predict/SKILL.md` and write the
+5-persona verdict into the PR, instead of running `/gflow:predict`.
+
 ## When in doubt
 
+
 Read [docs/INDEX.md](INDEX.md). It has a topic-shortcut block at the bottom that answers most "where do I find…?" questions in one hop.

{gflow_cli-0.12.0 → gflow_cli-0.14.0}/docs/CHARACTER.md

@@ -8,8 +8,8 @@
 > built **greenfield off `develop`, NOT stacked on #123** (that branch is CONFLICTING and likeness-specific;
 > see [Design decisions](#11-design-decisions-post-predict)).
 
-> **Shipped scope:** `gflow character create` + `list` + `show` + `voices`. The reuse path
-> `gflow video --character` (Phase 3), `gflow image --character`, and `gflow character rm` are **not yet
+> **Shipped scope:** `gflow character create` + `list` + `show` + `voices` + `rm`. The reuse path
+> `gflow video --character` (Phase 3) and `gflow image --character` are **not yet
 > implemented** — see [Backlog](#14-backlog--not-yet-implemented).
 
 > **Status (2026-06-02, LIVE-VERIFIED):** the create saga + character-editor UI generation are **shipped**
@@ -260,8 +260,8 @@ both normalize to the canonical `Charon`) and sets `audioReferences[].presetVoic
 The `create` / `list` / `show` / `voices` commands below are **shipped and
 live-verified in v0.12.0** (the user-facing reference lives in
 [USAGE § `gflow character`](USAGE.md#gflow-character)). The `gflow video --character`
-reuse path, `gflow image --character`, and `gflow character rm` remain
-**backlog** (rows marked *not yet implemented*).
+reuse path and `gflow image --character` remain **backlog** (rows marked *not
+yet implemented*). `gflow character rm` is **shipped** (see the table below).
 
 | Command | Maps to |
 |---|---|
@@ -270,7 +270,7 @@ reuse path, `gflow image --character`, and `gflow character rm` remain
 | `gflow character show --project <id> (--id <entityId> \| --name <displayName>) [--json]` *(SHIPPED v0.12.0)* | projectInitialData (single); name collision → exit 11 with disambiguation hint |
 | `gflow character voices [--json]` *(SHIPPED v0.12.0)* | list the 29 preset voices (name / description / sample-url); language-agnostic discovery, mirrors `gflow models --json` |
 | `gflow video … --character <id>` *(repeatable → multi-ref)* | **not yet implemented** (Phase 3) — `referenceEntities` on `video:batchAsyncGenerateVideoReferenceImages` |
-| `gflow character rm <id>` | **not yet implemented** — entity delete verb uncaptured |
+| `gflow character rm` (`--id`/`--name`) | **Shipped v0.13.0 (#150)** — `POST flow:batchDeleteAssets` (Bearer; FREE — no reCAPTCHA/credit) |
 | `gflow image … --character <id>` | **not yet implemented** — image-path `referenceEntities` uncaptured |
 
 All commands take **`--project <id>` (required)** — every endpoint (`createEntity`, `projectInitialData`,
@@ -305,7 +305,7 @@ never hard-code wire names in user-facing help — see [[cli-model-aliases-verif
 ## 10. Open items
 
 See [§14 Backlog — not yet implemented](#14-backlog--not-yet-implemented) for the consolidated list. In
-short: `gflow video --character` reuse (Phase 3), `gflow image --character`, `gflow character rm`, live voice
+short: `gflow video --character` reuse (Phase 3), `gflow image --character`, live voice
 listing + `presetVoiceId` wire-case confirmation, custom-voice creation, `nanopro` picker live confirmation,
 and extra body angles. The optional creation-agent (`flowCreationAgent/sessions`,
 `flow.generateCharacterPrompt` archetypes) is not required for the scripted path; consider an `--archetype`
@@ -495,9 +495,8 @@ The following are explicitly **out of the shipped scope** and tracked for future
 - **Extra body angles beyond the built-in triptych.** The shipped body slot generates a single front/side/back
   triptych. Generating additional angles/poses (e.g. re-feeding the front view as a reference seed for a new
   slot) is a future enhancement.
-- **`gflow character rm` / `gflow image --character`.** The entity **delete** verb and the **image-path**
-  reuse (`referenceEntities` on the image endpoint) are uncaptured — deferred until their wire shapes are
-  reverse-engineered.
+- **`gflow image --character`.** The **image-path** reuse (`referenceEntities` on the image endpoint) is
+  uncaptured — deferred until its wire shape is reverse-engineered. (`gflow character rm` is now shipped, #150.)
 - **Set the Flow editor title field** so the editor isn't "Untitled Character" (see [§13.1 Known issues](#131-known-issues)).
   Investigate either the UI title box (with a Ctrl+A merge-bug workaround) or finding the dedicated title
   field/endpoint that the editor widget reads from, distinct from `entityInfo.displayName`.

{gflow_cli-0.12.0 → gflow_cli-0.14.0}/docs/DATA_LAYER.md

@@ -456,8 +456,6 @@ These are tracked in [`PLAN.md`](../PLAN.md) under the data-layer phase backlog.
 
 ## See also
 
-- [Spec](superpowers/specs/2026-05-24-data-layer-design.md) — original design document with goals, non-goals, and architectural rationale.
-- [Plan](superpowers/plans/2026-05-24-data-layer.md) — task-by-task implementation plan.
 - [`CONFIGURATION.md`](CONFIGURATION.md) — env-var reference.
 - [`EXTERNAL_STORAGE.md`](EXTERNAL_STORAGE.md) — S3, MinIO, and GCS output configuration.
 - [`USAGE.md`](USAGE.md) — `gflow data media` command reference.

{gflow_cli-0.12.0 → gflow_cli-0.14.0}/docs/DEVELOPMENT.md

@@ -131,6 +131,7 @@ This repo is actively developed with Claude Code (see [CLAUDE.md](../CLAUDE.md))
 ## See also
 
 - [CONTRIBUTING.md](../CONTRIBUTING.md) — TDD, quality gates, how to add a route, commit style
+- [docs/GOVERNANCE_BENCHMARK.md](GOVERNANCE_BENCHMARK.md) — calibrating the advisory materiality gate (false-positive / coverage backtest)
 - [docs/GITHUB.md](GITHUB.md) — GitHub PR triage, external fork handling, SonarCloud scenarios
 - [RELEASE.md](../RELEASE.md) — release checklist, PyPI/GitHub publishing, tag protocol
 - [CHANGELOG.md](../CHANGELOG.md) — version history