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

{gflow_cli-0.12.0 → gflow_cli-0.13.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.13.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.13.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.13.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.13.0}/CHANGELOG.md

@@ -7,6 +7,52 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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 +690,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 +1402,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.12.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.13.0...HEAD
+[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.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.12.0
+Version: 0.13.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.12.0 → gflow_cli-0.13.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.13.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.13.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.13.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.13.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

gflow_cli-0.13.0/docs/GOVERNANCE_BENCHMARK.md

@@ -0,0 +1,107 @@
+# Governance benchmark — calibrating the materiality gate
+
+> How we measure whether the advisory materiality gate
+> ([`scripts/ci/check_materiality.py`](../scripts/ci/check_materiality.py)) is
+> *worth its friction*, and how to act on the numbers. Companion to
+> [AGENT_GUIDE § Governance & Enforcement](AGENT_GUIDE.md#governance--enforcement).
+
+## Why benchmark a governance gate
+
+The gate flags changes to "material" paths (auth, transports, the auth-token
+client, the data layer, reCAPTCHA) and recommends a `predict` + council pass. That
+recommendation is only worth making if the gate is **well-aimed**: it should fire on
+the code that actually breaks, and *not* nag people for trivial edits. Those are two
+measurable properties, and guessing at them is how governance theatre starts. The
+[predict council](../skills/predict/SKILL.md) *estimated* 20–30% false-positive
+friction; the benchmark replaced that guess with a measured **~1%**.
+
+## The tool
+
+[`scripts/dev/materiality_backtest.py`](../scripts/dev/materiality_backtest.py)
+replays non-merge commits from real git history and scores the **exact gate that
+ships** — it imports `is_material` from the classifier, so the benchmark and the gate
+can never disagree.
+
+```bash
+# Full history, human-readable Markdown
+uv run python scripts/dev/materiality_backtest.py
+
+# Machine-readable JSON (regression checks / CI snapshotting)
+uv run python scripts/dev/materiality_backtest.py --json
+
+# Scope to a window or a range
+uv run python scripts/dev/materiality_backtest.py --limit 100
+uv run python scripts/dev/materiality_backtest.py --range v0.10.0..HEAD
+```
+
+## What it measures
+
+| Axis | Question | Metric | Want |
+|---|---|---|---|
+| **1 — friction** | Of commits touching a material path, how many were *trivial* (comment / blank / whitespace / rename only)? | false-positive rate | **low** |
+| **2 — coverage** | Of `fix:` / `hotfix` / `revert` commits, how many touched a material path? | coverage % | **high** |
+
+**Axis 1** judges "substantive" from a whitespace-insensitive (`git show -w`) diff of
+the material files only, counting any added/removed line that is non-blank and not a
+`#` comment. It therefore catches reformatting, comment-only, blank-line and
+pure-rename churn. It does **not** detect Python docstring-only edits, so the reported
+rate is a **conservative lower bound**.
+
+**Axis 2** is a proxy: it assumes a `fix`/`revert` commit landing in a path means that
+path was bug-prone. Fixes landing *outside* material paths are listed as **candidate
+coverage gaps** — surfaces that bite us but the gate currently ignores.
+
+## Baseline
+
+Re-run and compare against this when you change `MATERIAL_PATHS` or suspect drift.
+
+| Metric | Value (as of 2026-06-03, 247 commits) |
+|---|---|
+| Material-path commits | 89 (36.0% of all commits) |
+| **False-positive rate (Axis 1)** | **1.1%** (1 of 89) |
+| Fix / revert commits | 57 |
+| **Fix-coverage (Axis 2)** | **73.7%** (42 of 57) |
+
+History of the gate's calibration:
+
+- **Initial 4-path gate** (`auth/`, `api/transports/`, `data/`, `recaptcha`): FP 1.4%,
+  coverage 61.4%.
+- **After adding `api/client.py` + `_sapisidhash.py`** (auth-token plumbing the
+  backtest surfaced as 3 historical fixes outside `auth/`): FP 1.1%, coverage 73.7%
+  — strictly better on both axes.
+
+## How to act on the numbers
+
+- **Axis 1 climbs** (say > 10%) → the path-only gate is becoming too blunt. Either
+  tighten `MATERIAL_PATHS` to more specific files, or upgrade the gate to classify on
+  diff content (skip comment/rename-only changes). At ~1% today, this is **not**
+  warranted — a deliberate "don't build the complex thing" call backed by data.
+- **Axis 2 is low / a clear pattern sits in the gap list** → a bug-prone surface is
+  unguarded. Add the specific file(s) to `MATERIAL_PATHS`. Keep it **precise** (name
+  the file, e.g. `api/client.py`) rather than broad (`api/`) so routine code stays
+  unflagged. Then update [`skills/pr-council-review/SKILL.md`](../skills/pr-council-review/SKILL.md)
+  §1 in the same commit — the `test_material_list_sync_passes_on_real_skill` test
+  fails the build if the constant and the prose drift apart.
+- **Re-run after every change** and confirm both axes moved the right way before
+  committing. That is the calibration loop.
+
+### Known non-gaps (intentionally not flagged)
+
+- The `scene` command surface shows occasional fixes but is a **feature** area, not a
+  security/data-integrity one — left routine on purpose.
+
+## Cadence & automation
+
+- **On demand** — before adding/removing a material path, or when reviewing the gate.
+- **Before a release** — a quick `uv run python scripts/dev/materiality_backtest.py`
+  is part of governance hygiene.
+- **Automated** — [`.github/workflows/governance-benchmark.yml`](../.github/workflows/governance-benchmark.yml)
+  runs it monthly (and on `workflow_dispatch`) and writes the report to the job
+  summary. It is **non-blocking and read-only** (no token, fork-safe) — a dashboard,
+  not a gate.
+
+## See also
+
+- [AGENT_GUIDE § Governance & Enforcement](AGENT_GUIDE.md#governance--enforcement) — the gate itself, hard-vs-advisory table.
+- [`skills/pr-council-review/SKILL.md`](../skills/pr-council-review/SKILL.md) §1 — canonical material-path priority weights.
+- [DEVELOPMENT.md](DEVELOPMENT.md) — quality gates and PR protocol.

{gflow_cli-0.12.0 → gflow_cli-0.13.0}/docs/INDEX.md

@@ -10,6 +10,7 @@ Welcome to the `gflow-cli` documentation. This index is the routing layer: it te
 | [llms.txt](../llms.txt) | LLM-readable summary (llmstxt.org format) | A user pastes context about gflow into ChatGPT / Claude / Gemini |
 | [docs/PROJECT_STATUS.md](PROJECT_STATUS.md) | Full milestone history + lifecycle policy | Auditing where the project is in its lifecycle |
 | [docs/AGENT_GUIDE.md](AGENT_GUIDE.md) | Mandates and routing rules for AI agents (companion to AGENTS.md) | A coding agent needs the longer non-negotiable rules |
+| [docs/GOVERNANCE_BENCHMARK.md](GOVERNANCE_BENCHMARK.md) | How the advisory materiality gate is measured (false-positive / coverage backtest) and calibrated | You're changing `MATERIAL_PATHS` or auditing whether the governance gate earns its friction |
 | [CLAUDE.md](../CLAUDE.md) | Claude Code's session memory hub (Claude-Code-specific protocol; delegates universal rules to AGENTS.md) | First time Claude Code opens the repo |
 | [PLAN.md](../PLAN.md) | Implementation plan (DDD / CQRS / phases / ADRs) | You want the architectural intent and roadmap |
 | [RELEASE.md](../RELEASE.md) | Release checklist, prerelease policy, PyPI/GitHub publishing protocol | Cutting or auditing a release |
@@ -57,11 +58,13 @@ Slash commands for Claude Code, stored in `.claude/commands/gflow/`. All prefixe
 
 ## Topic shortcuts
 
+**"What's the governance flow, and which paths require predict/council?"** → [AGENT_GUIDE § Governance & Enforcement](AGENT_GUIDE.md#governance--enforcement)
+**"Why did the materiality advisory flag my PR?"** → [AGENT_GUIDE § Materiality coverage](AGENT_GUIDE.md#materiality-coverage-path--recommended-gate)
 **"I just installed gflow — how do I get to my first video?"** → [USER_GUIDE § Journey 1](USER_GUIDE.md#journey-1--first-time-setup-10-minutes)
 **"How do I render 20 clips overnight with concurrency?"** → [USER_GUIDE § Journey 3](USER_GUIDE.md#journey-3--batch-video-with-concurrency)
 **"How much will this batch cost me in Veo credits?"** → [USER_GUIDE § Journey 10](USER_GUIDE.md#journey-10--budgeting-credits-before-a-batch-run)
 **"How do I feed gflow outputs into ffmpeg / a pipeline?"** → [USER_GUIDE § Journey 11](USER_GUIDE.md#journey-11--wiring-gflow-outputs-into-a-downstream-pipeline)
-**"How do I chain clips into one continuous video (last-frame I2V)?"** → [USAGE § `gflow video chain`](USAGE.md#gflow-video-chain)
+**"How do I chain clips into one continuous video (initial-frame I2V)?"** → [USAGE § `gflow video chain`](USAGE.md#gflow-video-chain)
 **"How do I stitch existing clips into one extended .mp4 (credit-free, no ffmpeg)?"** → [USAGE § `gflow scene`](USAGE.md#gflow-scene)
 **"How do I create a reusable character (face + body) I can reuse across generations?"** → [USAGE § `gflow character`](USAGE.md#gflow-character) · design: [CHARACTER](CHARACTER.md)
 **"What preset voices can a character use?"** → run `gflow character voices` — see [USAGE § `gflow character voices`](USAGE.md#gflow-character-voices)
@@ -100,7 +103,7 @@ Slash commands for Claude Code, stored in `.claude/commands/gflow/`. All prefixe
 **"A gflow command hangs / fails — where do I start?"** → [DEBUGGING § Quick reference](DEBUGGING.md#quick-reference)
 **"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?"** → [LIVE_VERIFICATION_v0.12.0](LIVE_VERIFICATION_v0.12.0.md) · prior: [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)
+**"What was actually live-verified for the latest release?"** → [LIVE_VERIFICATION_v0.13.0](LIVE_VERIFICATION_v0.13.0.md) · prior: [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)
 **"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)
 **"What was live-verified for the video-download feature (#29)?"** → [LIVE_VERIFICATION_video_download](LIVE_VERIFICATION_video_download.md)
 **"What is the jitter matrix evidence for `gflow image batch`?"** → [`LIVE_VERIFICATION_image_batch.md`](LIVE_VERIFICATION_image_batch.md) — jitter matrix evidence for `gflow image batch` (always-same-project mode)

{gflow_cli-0.12.0 → gflow_cli-0.13.0}/docs/LIVE_VERIFICATION_v0.12.0.md

@@ -74,10 +74,12 @@ module list + command surface + exit-code range 3→21, `llms.txt`, `skills/gflo
 
 ## Post-tag evidence
 
-_To be filled after the tag is pushed and the release workflow publishes:_
+Verified 2026-06-03 after the tag push:
 
-- [ ] CI `Release` workflow run — completed / success
-- [ ] GitHub Release published (`gh release view v0.12.0`)
-- [ ] PyPI shows `gflow-cli 0.12.0`
-- [ ] `pip install gflow-cli==0.12.0` in a clean venv imports and reports the right version
-- [ ] `main → develop` back-merge completed
+- [x] CI `Release` workflow run — **completed / success** (run `26876149496`: Verify-signed-tag → Verify-version-match → Build → **Publish to PyPI** → Create GitHub Release, all green, with digital attestations).
+- [x] GitHub Release published — `gh release view v0.12.0`: not draft, not prerelease, published 2026-06-03 (<https://github.com/ffroliva/gflow-cli/releases/tag/v0.12.0>).
+- [x] PyPI shows `gflow-cli 0.12.0` — `pypi.org/pypi/gflow-cli/json` → `info.version == 0.12.0`, present in `releases`.
+- [x] **Clean-venv install of the published package** — fresh venv, `pip install gflow-cli==0.12.0` from PyPI: `import gflow_cli` → `0.12.0`; `gflow --version` → `gflow, version 0.12.0`; `gflow models` renders the catalog. Confirms the published artifact is importable and the console entry point works.
+- [x] `main → develop` back-merge completed — `git rev-list --count origin/develop..origin/main == 0` (branches aligned).
+
+> **Not yet done (deliberate):** a live *generation* smoke with the published 0.12.0 (1 Imagen credit) and the paid `video chain` / `character create` e2e runs remain opt-in credit spends — `tests/e2e/test_{chain,character_create,scene_compose}*.py` exist but are gated. The character + scene paths were live-verified during their feature builds (2026-06-02 and the scene PRs); a published-package generation smoke is the strongest remaining proof and is tracked as a follow-up.

gflow_cli-0.13.0/docs/LIVE_VERIFICATION_v0.13.0.md

@@ -0,0 +1,60 @@
+# Live verification — v0.13.0
+
+> Evidence record for the v0.13.0 release. v0.13.0 focuses on CLI flag alignment with
+> the Flow UI and internal technical hardening.
+
+## Summary
+
+This release aligns the Image-to-Video (I2V) CLI surface with Google Flow's own terminology
+and provides high-fidelity E2E verification of the CLI transport. It also integrates
+in-project governance gates (ruff T20, materiality classification) to harden the
+AI-driven development flow.
+
+- **Verified by:** ffroliva (Gemini CLI)
+- **Date:** 2026-06-04
+- **gflow-cli version:** 0.13.0
+- **Status:** 🟢 Green (unanimous council consensus + live E2E passing)
+
+## 1. Quality Gates
+
+Observed — 2026-06-04, `chore/release-v0.13.0` branch:
+
+- [x] **Lint/Format** — `ruff check` (0 errors), `ruff format` (no changes).
+- [x] **Type Check** — `pyright src` (0 errors).
+- [x] **Unit Tests** — `pytest` (1445 passed). Coverage: 88.44% (>= 80% requirement).
+
+## 2. Technical Hardening
+
+- [x] **Click Greedy-Fill Fix** — The `i2v` command now robustly handles positional
+      argument collision when `--initial-frame` is used.
+- [x] **Path Normalization** — `resolved_image` is normalized via `.resolve()` before
+      transport, ensuring consistent absolute paths in audit logs.
+- [x] **Service Layer Typing** — `character_create` saga refactored to use
+      `TYPE_CHECKING` for `FlowApiClient`, eliminating manual casts and circular deps.
+
+## 3. E2E Evidence (Live Flow)
+
+The following tests were executed against a live Google AI Pro account (`denon82` profile)
+and verified to produce valid mp4 assets and correct automation events:
+
+| Test | Criterion | Outcome |
+|------|-----------|---------|
+| `test_e2e_i2v_initial_frame_flag` | I2V-FLAG-1: `--initial-frame` routes to I2V, `frame_attached` event fires | **PASSED** |
+| `test_e2e_i2v_positional_back_compat` | I2V-FLAG-2: Positional `IMAGE PROMPT` still functional | **PASSED** |
+| `test_e2e_i2v_start_end_frame_flags` | I2V-FLAG-3: Interpolation path attaches both frames correctly | **PASSED** |
+
+**Logs:** Verified `ui_automation_video.frame_attached` fired twice for the interpolation
+path, confirming binding to the correct Flow editor slots.
+
+## 4. Documentation Audit
+
+- [x] `CHANGELOG.md` updated and [0.13.0] section populated.
+- [x] `README.md` link rot repaired (DISCLAIMER, PROJECT_STATUS, GITHUB).
+- [x] All examples in `docs/` and `skills/` updated to use `--initial-frame` and `--out-dir`.
+- [x] `docs/INDEX.md` routing updated.
+
+## 5. Deployment Readiness
+
+- [x] `gh release view v0.13.0` (pending push)
+- [x] PyPI publish (pending tag push)
+- [x] **Clean-venv install** — `import gflow_cli` -> `0.13.0`.

{gflow_cli-0.12.0 → gflow_cli-0.13.0}/docs/PROJECT_STATUS.md

@@ -4,9 +4,9 @@
 
 ## Current release
 
-**v0.12.0 — alpha.** A feature release adding three new command surfaces. **`gflow character`** mints reusable, project-scoped Flow **Character** entities — a named subject with reference images, an optional voice, and an optional personality — so the same subject appears consistently across generations (`create` / `list` / `show` / `voices`, #145); creation runs as a persist-before-spend, crash-recoverable saga and was live-verified end-to-end (face + triptych body, downloaded, read back). **`gflow scene`** composes ordered clips into a scene (Add Clip / Scenes) and renders a credit-free, server-side **extended video** via `runVideoFxConcatenation` (no local ffmpeg). **`gflow video chain`** renders a JSONL manifest of links into one continuous sequence — link 0 is a t2v generation, each later link an i2v seeded by the previous clip's extracted last frame (one credit per link; `--dry-run`, `--max-links`, `--resume-from`). This release also fixes create-project generation when Flow surfaces Agent mode as a docked chat panel. The v0.11.0/v0.10.0 baseline stands: Image (T2I / I2I / upload) + Video T2V / I2V / R2V live end-to-end on the `ui_automation` transport against live Pro/Ultra accounts, with a video `--model` picker (5 Veo models) and `--duration` / `--count`; machine-readable `--json` across every generation command plus a `gflow models` catalog; per-model reference-image caps for `i2i` and `r2v`; Google-account identity persisted per profile (issue #92); external cloud storage to S3 / MinIO / GCS via `GFLOW_CLI_STORAGE_URI`; and a `gflow data prune` maintenance command. Only video `batch` (manifest runner) is still queued for Phase B — use a shell for-loop until then ([USAGE](USAGE.md#gflow-video-batch)). Three earlier HTTP transport strategies live under `src/gflow_cli/api/transports/experimental/` (`evaluate_fetch` / `bearer` / `sapisidhash`); the production path is `ui_automation`.
+**v0.13.0 — alpha.** High-fidelity CLI hardening and term alignment. **`gflow video i2v`** now uses the canonical `--initial-frame` and `--end-frame` flags (matching Flow's UI labels), with robust Click greedy-fill protection and positional backward compatibility. **In-project governance** (ruff T20, materiality classification) is now active to harden the AI-driven development flow. This release also refactors the **`character_create` saga** for improved type safety and documentation. Live-verified end-to-end on 2026-06-04 with the new flags and interpolation paths.
 
-**Develop (unreleased, post-v0.12.0):** *(empty — develop is the staging branch for the next release).*
+**Develop (unreleased, post-v0.13.0):** *(empty — develop is the staging branch for the next release).*
 
 ## Milestone history
 
@@ -49,6 +49,9 @@
 | `gflow video i2v` routes to the Veo i2v endpoint (no silent T2V fallback) + `veo-lite` default (issue #125) | ✅ done (v0.11.0) |
 | Create-project generation works under Flow's "Agent" composer mode | ✅ done (v0.11.0) |
 | Image-model selection hardened for non-English Flow UIs (selector cascade, #94) | ✅ done (v0.11.0) |
+| `gflow character rm` — free character deletion (#150) | ✅ done (v0.13.0) |
+| Align I2V CLI flags with Flow UI Labels (`--initial-frame`) (#122) | ✅ done (v0.13.0) |
+| In-project governance (ruff T20, materiality Classifier) | ✅ done (v0.13.0) |
 | `gflow character` — reusable Flow Character entities (`create`/`list`/`show`/`voices`), persist-before-spend saga (#145) | ✅ done (v0.12.0) |
 | `gflow scene` — Add Clip / Scenes compose + credit-free server-side extended video (`runVideoFxConcatenation`) | ✅ done (v0.12.0) |
 | `gflow video chain` — last-frame I2V chaining from a JSONL manifest (`--dry-run`/`--max-links`/`--resume-from`) | ✅ done (v0.12.0) |