gflow-cli 0.7.0__tar.gz → 0.8.1__tar.gz

gflow_cli-0.8.1/.claude/commands/gflow/doc-review.md

@@ -0,0 +1,259 @@
+---
+description: Use before cutting any gflow-cli release or after a major documentation change — systematic council-driven audit that combines a mechanical 7-section checklist with a 3-agent parallel review (completeness / cross-reference / drift). Produces a consensus verdict and a concrete fix list.
+---
+
+# `/gflow:doc-review` — Documentation Review Gate
+
+Run this gate before cutting a release. Two phases:
+
+1. **Mechanical checks** (sections 1–7 below) — fast, scripted, deterministic. Run inline.
+2. **LLM council audit** (section 8) — 3 parallel review subagents, then consensus synthesis. The mechanical pass catches stale strings and dead links; the council catches drift between docs, fictional claims, and gaps a human reader would notice.
+
+Every item reports **PASS / UPDATED / WARN / FAIL**. Any **FAIL** or any **RED** council verdict blocks the release.
+
+> **Provenance:** the council protocol below was validated on the v0.8.1 docs refresh release (2026-05-23). The audit found 11 fixable issues that the mechanical checklist alone missed (e.g., the `experimental/` subpackage fiction in 3 files, the `gflow video i2v` non-working hero snippet in README). Keep the council step — it pays for itself.
+
+---
+
+## 0 · Pre-flight
+
+- Confirm you are on the release branch (`release/vX.Y.Z` or `hotfix/...`), not on `develop` or `main`.
+- If a release spec exists at `docs/superpowers/specs/YYYY-MM-DD-*-design.md`, identify it now — the council auditors will use it as the ground truth for "what was supposed to ship."
+- If there is no spec, that is also fine — the council will work from the docs alone, but flag the absence as a process risk.
+
+---
+
+## 1 · Version references
+
+Check these files for stale version strings (old numbers, outdated status labels):
+
+| File | What to verify |
+|---|---|
+| `README.md` | Status badge, "Project status" section, install example |
+| `AGENTS.md` | Module list, exit-code range, dev-environment commands |
+| `llms.txt` | Header summary (Python version, stable surface claims) |
+| `CLAUDE.md` | "Active phase" pointer if present |
+| `PLAN.md` | Phase status (`IN PROGRESS` / `DONE`) and version annotations |
+| `KNOWN_ISSUES.md` | `Open` entries resolved by this release → move to `Resolved` with evidence |
+| `CHANGELOG.md` | `[Unreleased]` empty; link footer matches new version |
+| `pyproject.toml` + `src/gflow_cli/__init__.py` | Both set to the new version |
+| `docs/PROJECT_STATUS.md` | "Current release" subsection + milestone-history row for this version |
+
+Quick grep:
+
+```bash
+grep -rn "v[0-9]\+\.[0-9]" README.md AGENTS.md llms.txt CLAUDE.md PLAN.md KNOWN_ISSUES.md CHANGELOG.md pyproject.toml docs/PROJECT_STATUS.md
+```
+
+Historical references in `CHANGELOG.md`, `docs/LIVE_VERIFICATION_v*.md`, and milestone-history rows in `docs/PROJECT_STATUS.md` are allowed.
+
+---
+
+## 2 · `docs/INDEX.md` completeness
+
+Every `.md` in `docs/` needs an entry; every entry must point to a real file. AGENTS.md and llms.txt also need rows since they are agent-facing entry points.
+
+```bash
+# Files in docs/ missing from INDEX.md
+for f in docs/*.md; do
+  grep -q "$(basename "$f")" docs/INDEX.md || echo "MISSING from INDEX: $f"
+done
+
+# Entries in INDEX.md pointing to deleted files
+grep -o 'docs/[^)]*\.md' docs/INDEX.md | while read path; do
+  [ -f "$path" ] || echo "DEAD LINK in INDEX: $path"
+done
+
+# AGENTS.md, llms.txt rows present?
+grep -E "AGENTS\.md|llms\.txt" docs/INDEX.md || echo "MISSING: agent-facing root files row"
+```
+
+---
+
+## 3 · Per-release evidence file
+
+After each release a `docs/LIVE_VERIFICATION_vX.Y.Z.md` must exist.
+
+- Latest version has one (create stub if live run already documented elsewhere).
+- `docs/INDEX.md` "latest release" cue points to it.
+- Previous versions' files are preserved (historical record — never delete).
+- File contains both a **Pre-tag gates** section (filled before signing) and a **Post-tag evidence** section (filled after publish).
+
+---
+
+## 4 · Doc-link validation
+
+Run the link checker:
+
+```powershell
+$env:PYTHONUTF8=1
+uv run python scripts/ci/check_doc_links.py
+```
+
+Expected: `All links resolved across N files.` (exit 0). Broken links must be fixed in source docs before continuing — do not edit the script to ignore them.
+
+If `scripts/ci/check_doc_links.py` is absent, create it from the v0.8.1 plan (it is a 30-line stdlib-only Python script).
+
+---
+
+## 5 · `.claude/commands/gflow/` skill files
+
+Scan all skills for stale phase/version references:
+
+```bash
+grep -rn "v[0-9]\+\.[0-9]\|Phase [A-Z0-9]" .claude/commands/gflow/
+```
+
+Update in the release prep commit if any references are wrong. The `release.md` skill's step list and the `plan.md` skill's phase pointers age fastest.
+
+---
+
+## 6 · CHANGELOG link footer
+
+```bash
+tail -10 CHANGELOG.md
+```
+
+Must read: `[Unreleased]: …compare/vNEW_VERSION…HEAD` and each prior `[X.Y.Z]: …compare/vPREV…vCURR`.
+
+---
+
+## 7 · Memory files
+
+Check `C:\Users\ffrol\.claude\projects\C--development-github-gflow-cli\memory\`:
+
+| File | What to verify |
+|---|---|
+| `MEMORY.md` | All listed files exist; no dangling entries |
+| `phase-b-followups.md` | Items shipped in this release marked done |
+| `video-generation-spec.md` | PR/status accurate |
+| `image-generation-401-next.md` | Resolution status and evidence pointer still valid |
+| `release-signing.md` | Procedure section matches what was actually done |
+| `release-back-merge-gap-recovery.md` | Still relevant; gap from any prior release recorded |
+
+```bash
+cd "C:\Users\ffrol\.claude\projects\C--development-github-gflow-cli\memory"
+grep -o '\[.*\]([^)]*\.md)' MEMORY.md | grep -o '([^)]*)' | tr -d '()' | while read f; do
+  [ -f "$f" ] || echo "DEAD LINK: $f"
+done
+```
+
+---
+
+## 8 · LLM council audit (NEW — required for every release ≥ v0.8.1)
+
+The mechanical checks above catch stale strings, dead links, and missing files. They do **not** catch:
+
+- A doc claiming a subpackage exists when it does not (no string sweep would notice).
+- Two docs covering the same topic with subtly different facts.
+- A working-looking hero snippet that points to a stub command (`gflow video i2v` returned "not yet available" but appeared as a production loop above the fold in v0.8.1).
+- A user-facing onboarding gap that a fresh reader would hit immediately.
+
+The council does. Dispatch three review subagents **in parallel** (they are read-only and independent). Each writes its verdict to `tmp/council/`.
+
+### Setup
+
+```bash
+mkdir -p tmp/council
+```
+
+### Auditor 1 — Completeness
+
+Role: as a fresh user / fresh AI agent, **what do you need that isn't there?**
+
+Audit:
+- `README.md`, `AGENTS.md`, `llms.txt`, `CLAUDE.md`, `docs/INDEX.md`, `docs/PROJECT_STATUS.md`
+- `docs/ARCHITECTURE.md` (especially any new sections)
+- `docs/LIVE_VERIFICATION_v*.md` (latest)
+- `CHANGELOG.md` (just the new entry)
+- `pyproject.toml`
+- The release spec at `docs/superpowers/specs/` (if present)
+- The implementation plan at `docs/superpowers/plans/` (if present)
+
+Output to `tmp/council/01-completeness.md` with verdict GREEN / YELLOW / RED and four sections:
+1. Critical gaps (block release)
+2. Important gaps (fix before next release)
+3. Nice-to-haves (track for next version)
+4. What's done well (preserve)
+
+### Auditor 2 — Cross-reference & alignment
+
+Role: do the docs **agree with each other**? Where two files cover the same topic, do they say the same thing?
+
+Check:
+- Install instructions, auth flow, headed-browser story, version number, Python requirement — all match exactly?
+- Internal `[X](path)` links — files exist AND claims at the link target equivalent to the linking-doc's claim?
+- Routing chain (README → AGENTS.md → CLAUDE.md → docs/INDEX.md) — consistent? Any contradictions?
+- CHANGELOG vs PROJECT_STATUS — milestone history matches changelog entries?
+- Spec vs implementation — does the shipped state match the design spec?
+
+Output to `tmp/council/02-crossref.md` with verdict + four sections (inconsistencies / drift / broken anchors / well-aligned).
+
+### Auditor 3 — Drift & staleness
+
+Role: does the documentation match the actual code and project state? **Where are claims unverifiable, contradicted by reality, or referencing things that no longer exist?**
+
+Check empirically (every claim needs `ls` / `grep` / `cat` evidence cited inline):
+- Version claims — `pyproject.toml`, `__init__.py`, every "v0.8.1 — alpha" statement agree?
+- Module / file claims — every `src/gflow_cli/{...}` module list verified against the actual source tree?
+- Subpackage claims (e.g., `experimental/`) — do those directories exist?
+- CLI command claims in hero snippets — is the subcommand really implemented? Does it actually do what the example shows, or is it a stub?
+- Exit-code claims — verify the range against `errors.py::EXIT_CODE_MAP`.
+- Skill files, GIF assets, slash-command files — exist at the paths claimed?
+
+Output to `tmp/council/03-drift.md` with verdict + three sections (fictional claims / stale references / verified-real).
+
+### Consensus
+
+After all three reports return:
+
+1. Read all three. List every distinct finding.
+2. Tier the findings:
+   - **Tier 1 (release-blocking)** — any RED verdict, any "block release" finding, any fictional claim that ships to PyPI.
+   - **Tier 2 (important polish)** — drift between related docs, minor mismatches, missing-but-recoverable references.
+   - **Tier 3 (track for later)** — nice-to-haves, prose improvements, deferred features.
+3. Apply Tier 1 fixes immediately (block the release until done).
+4. Apply Tier 2 fixes if the release schedule permits, otherwise open issues.
+5. Tier 3 → backlog (memory `phase-X-followups.md` or a new GitHub issue).
+
+Synthesize a single fix-plan comment under the relevant `LIVE_VERIFICATION_vX.Y.Z.md` `Pre-tag gates` entry for `/gflow:doc-review`:
+
+> _Council verdict: <GREEN|YELLOW|RED> across all 3 auditors. <N> findings; <M> Tier 1 fixed in commit <SHA>, <K> Tier 2 fixed in commit <SHA2>, <J> Tier 3 deferred to backlog. Council reports at `tmp/council/0{1,2,3}-*.md` (local-only)._
+
+If any auditor returns RED, **stop and escalate to the user**. Do not apply fixes blindly to a RED finding — it usually means the doc is wrong about the code, the code is wrong about the doc, or both.
+
+---
+
+## Output format
+
+After each section write one line:
+
+```
+[0] Pre-flight        — PASS (release spec at docs/superpowers/specs/YYYY-MM-DD-*.md)
+[1] Version refs      — PASS
+[2] INDEX completeness — UPDATED (added AGENTS.md row)
+[3] Evidence file     — PASS
+[4] Doc-link check    — PASS (9 files, 0 broken)
+[5] Skill files       — UPDATED (refreshed /gflow:plan phase pointer)
+[6] CHANGELOG footer  — PASS
+[7] Memory files      — WARN: phase-b-followups.md has shipped items not yet ticked
+[8] Council audit     — YELLOW (11 findings, all fixed in commit abc1234)
+```
+
+Then list every **UPDATED** change, every **WARN** / **FAIL** finding, and the council fix list for the user to review.
+
+---
+
+## Integration with `/gflow:release`
+
+This skill is invoked at **step 9** of `/gflow:release` (between "review commands for staleness" and "commit the release prep"). The mechanical pass (sections 1–7) is the same as before; the council audit (section 8) is the new requirement and runs after the mechanical pass succeeds.
+
+All discovered fixes are folded into the release prep commit unless genuinely unrelated to the release.
+
+---
+
+## Post-release: memory consolidation
+
+After the release ships and the back-merge completes, the **release spec** and **implementation plan** under `docs/superpowers/{specs,plans}/` are project-management artifacts, not user-facing docs. The durable knowledge they contain (patterns learned, governance rules, architecture decisions) should be extracted into project memory at `~/.claude/projects/<...>/memory/`, then the spec/plan files **deleted from the repo** in a final cleanup commit.
+
+This keeps the public-facing `docs/` tree focused on what users and contributors need, while the planning artifacts live on as memory entries usable by future Claude Code sessions. See the `release-back-merge-gap-recovery` memory and the v0.8.1 release commit history for an example.

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

@@ -0,0 +1,168 @@
+---
+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).
+
+## 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 clean working tree.**
+
+```bash
+git status --short
+```
+
+Must be empty. If not, abort and tell the user to commit or stash first.
+
+**3. Verify `main` is up-to-date.**
+
+```bash
+git rev-parse --abbrev-ref HEAD     # must be "main"
+git fetch origin
+git rev-list HEAD..origin/main      # must be empty
+```
+
+If not on `main`, switch: `git checkout main && git pull origin main`.
+If `main` is behind, pull first.
+
+**4. Run quality gates.**
+
+Run `/gflow:check` — all gates must pass. Abort if any fail.
+
+**5. Create a release branch.**
+
+```bash
+git checkout -b chore/release-v<NEW_VERSION>
+```
+
+All release prep commits live here; this branch gets PR'd into `main`.
+
+**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:
+  ```
+  [Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v<NEW_VERSION>...HEAD
+  [<NEW_VERSION>]: https://github.com/ffroliva/gflow-cli/releases/tag/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 CHANGELOG.md
+git add docs/ .claude/commands/gflow/        # include any doc-review fixes
+git commit -m "chore(release): v<NEW_VERSION>"
+```
+
+**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.
+
+**13. Push the tag first** (bypasses branch protection; triggers the CI release workflow immediately):
+
+```bash
+git push origin v<NEW_VERSION>
+```
+
+CI will start building the release. Watch <https://github.com/ffroliva/gflow-cli/actions>.
+
+**14. Push the release branch and open the PR.**
+
+```bash
+git push origin chore/release-v<NEW_VERSION>
+```
+
+Open PR `chore/release-v<NEW_VERSION> → main` with title `chore(release): v<NEW_VERSION>`. Merge it once CI is green. (The release workflow already ran from the tag push in step 13 — the PR is to keep `main` up-to-date with the bump commit.)
+
+**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
+
+- **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.
+- 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.8.1/.continue-here.md

@@ -0,0 +1,118 @@
+---
+phase: phase-b-video-download
+task: 0
+total_tasks: 6
+status: ready_to_execute
+last_updated: 2026-05-20T16:22:15.971Z
+---
+
+<current_state>
+Plan written and saved. No code written yet. Ready to execute Task 1 of 6.
+
+Branch: develop (clean, up-to-date after back-merge of main v0.7.0)
+Plan file: docs/superpowers/plans/2026-05-20-video-download-t2v-cli.md
+</current_state>
+
+<completed_work>
+
+This session (prior to plan writing):
+- v0.7.0 release protocol fixed: new /gflow:release (16 steps) with branch-protection-aware push, doc-review gate, back-merge step
+- New /gflow:doc-review skill created at .claude/commands/gflow/doc-review.md
+- PR #34 merged to develop; back-merge main (v0.7.0) → develop done (d012bcd)
+- Memory items D and F in phase-b-followups.md marked resolved
+- develop is fully clean and synced with main
+
+Plan tasks (NOT YET STARTED — all 6 remain):
+- Task 1: VideoResult dataclass in api/video.py
+- Task 2: _download_video helper on VideoGenerationMixin
+- Task 3: generate_video returns VideoResult, gains download=True param
+- Task 4: FlowApiClient.download_video wraps self.download()
+- Task 5: gflow video t2v CLI restored (--aspect / --profile / --out-dir)
+- Task 6: CHANGELOG entries
+</completed_work>
+
+<remaining_work>
+
+All 6 plan tasks. Execute in order — each has TDD steps (RED→GREEN→commit).
+
+Task 1: VideoResult dataclass
+  - Add to src/gflow_cli/api/video.py after VideoStatus
+  - Test in tests/api/test_video.py
+
+Task 2: _download_video on VideoGenerationMixin
+  - Add to src/gflow_cli/api/transports/ui_automation_video.py
+  - Uses page.request.get(routes.media_download_url(media_id), max_redirects=5, timeout=180_000)
+  - Test in tests/api/transports/test_ui_automation_video.py
+
+Task 3: Update generate_video signature
+  - Add download: bool = True param
+  - Return type VideoStatus → VideoResult
+  - After _poll_video_status: if download and status.succeeded → _download_video
+  - Both generate_video and _generate_video_locked change signatures
+
+Task 4: FlowApiClient.download_video
+  - 3-line wrapper: return await self.download(media_id, out_path)
+  - Add after download_image in src/gflow_cli/api/client.py
+  - Test in tests/api/test_client.py
+
+Task 5: cli_video.py T2V restoration
+  - Replace entire file content (plan has full replacement)
+  - Uses UiAutomationTransport directly (not FlowApiClient)
+  - prompt becomes required argument (was optional)
+  - New options: --aspect (9:16/16:9), --profile, --out-dir
+  - Test in tests/cli/test_cli_video.py
+
+Task 6: CHANGELOG
+  - Add entries under [Unreleased]
+</remaining_work>
+
+<decisions_made>
+
+- VideoResult(status: VideoStatus, local_path: Path | None) — new frozen dataclass,
+  NOT a tuple, for clean ergonomics (same pattern as GeneratedImage on image side)
+
+- generate_video is a breaking change (VideoStatus → VideoResult return type) —
+  acceptable in Phase B; no external callers known
+
+- _run_t2v uses UiAutomationTransport directly, NOT FlowApiClient —
+  YAGNI: FlowApiClient.generate_video wrapper deferred; transport pattern
+  proven by tmp/fetch_video.py
+
+- Download uses page.request.get (Playwright, follows 302 natively) NOT httpx —
+  httpx _download static method is image-only and doesn't follow redirects;
+  video needs the 302 to GCS followed with auth context
+
+- Aspect.from_cli() used in CLI (not a hand-rolled mapping) — already exists in
+  src/gflow_cli/api/video.py line 37
+
+- Default aspect for t2v CLI: 9:16 (PORTRAIT) — matches GenerateVideoRequest default
+</decisions_made>
+
+<blockers>
+None. Plan is fully self-contained and executable.
+</blockers>
+
+<context>
+Phase B of gflow-cli. Phase A shipped T2V transport (generate_video on
+UiAutomationTransport) in v0.7.0 but generate_video never downloaded the mp4.
+This plan adds the download primitive and wires the CLI.
+
+Key files to understand:
+- src/gflow_cli/api/video.py — VideoStatus, GenerateVideoRequest, Aspect.from_cli()
+- src/gflow_cli/api/transports/ui_automation_video.py — VideoGenerationMixin, generate_video, _poll_video_status
+- src/gflow_cli/api/routes.py — media_download_url(media_id) → getMediaUrlRedirect URL
+- src/gflow_cli/api/client.py — download() at ~line 510 (already handles the redirect)
+- src/gflow_cli/cli_video.py — all stubs, full replacement planned
+- tmp/fetch_video.py — throwaway proof-of-concept for the download approach
+
+After this plan, the remaining Phase B items are:
+- I2V on UiAutomationTransport (Mode.I2V raises NotImplementedError)
+- R2V on UiAutomationTransport (Mode.R2V raises NotImplementedError)
+- T2V portrait live verification (one credit, one run)
+- Listener-miss flake investigation
+</context>
+
+<next_action>
+Read docs/superpowers/plans/2026-05-20-video-download-t2v-cli.md then
+invoke superpowers:subagent-driven-development to execute Task 1.
+</next_action>

{gflow_cli-0.7.0 → gflow_cli-0.8.1}/.gitignore

@@ -75,3 +75,6 @@ samples/captured/flow_outgoing_*.json
 
 # Doc-council scratch dir (bundles + raw reviews + consensus matrix)
 .doc-council/
+
+worktrees/
+

gflow_cli-0.8.1/.planning/todos/pending/pr-38-review.md

@@ -0,0 +1,8 @@
+# PR #38 Review Tasks
+
+- [x] Task 1: Worktree Initialization
+- [x] Task 2: Compliance & Hygiene Check (FAILED DCO, found missing flag in _spawn_chrome)
+- [x] Task 3: Functional Verification (Unit/Integration) (PASSED 680 tests)
+- [x] Task 4: E2E Headless Validation (PASSED on Windows)
+- [x] Task 5: Windows Regression Check (PASSED)
+- [x] Task 6: Review Synthesis

gflow_cli-0.8.1/AGENTS.md

@@ -0,0 +1,78 @@
+# AGENTS.md — gflow-cli
+
+> Universal entry point for AI coding agents. Read this first; everything else routes from here.
+
+Supported tools that auto-discover this file: Cursor, Codex, Aider, Gemini CLI, Jules, Devin, Windsurf, Zed, Warp, opencode, RooCode, Amp, Junie, Phoenix, GitHub Copilot, VS Code, Factory, Augment, Semgrep, Kilo Code, UiPath. Claude Code reads [CLAUDE.md](CLAUDE.md), which cross-references this file.
+
+## Project at a glance
+
+- 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_image.py`, `cli_run.py`, `cli_video.py`, `config.py`, `errors.py`, `exceptions.py`, `image_batch.py`, `manifest.py`, `observability.py`, `paths.py`, `profile_store.py`.
+- 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 currently drives Flow via a **real Chrome session managed by Playwright** — `ui_automation` transport. Google's auth + reCAPTCHA stack rejects Playwright's bundled Chromium and most headless approaches. This is the project's defining trade-off:
+
+- ✅ Works end-to-end against live Pro/Ultra accounts.
+- ❌ Requires a saved Chrome profile, a display server for one-time login, and ~150 MB for Chromium.
+- ❌ Cannot run on serverless / headless CI workers without prerecorded profile transplant.
+- ❌ Per-account horizontal concurrency is capped by what one warm Page pool can drive.
+
+If you can help unblock a pure HTTP transport (especially for video generation, where HTTP 401 + reCAPTCHA mints currently block us), please open an issue — see the README "Architecture & current limitations" section.
+
+## Dev environment tips
+
+- `uv sync` then `uv run playwright install chromium`. No global Python install needed.
+- 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.
+
+## Testing instructions — The Impeccable Routine
+
+Run these gates in order before every commit:
+
+```powershell
+$env:PYTHONUTF8=1
+uv run python scripts/ci/check_repo_hygiene.py
+uv run ruff check src tests
+uv run ruff format --check src tests
+uv run pyright src
+uv run python -m pytest -q --cov=gflow_cli
+```
+
+Or invoke the wrapper: `/gflow:check`.
+
+- Use `pytest -m "not live and not e2e"` locally; full suite OOMs on small dev machines. Scope to changed dirs; trust CI for the full sweep.
+- TDD is non-negotiable. Coverage floor: 80% overall.
+- Live tests (`@pytest.mark.live`) opt in via `GFLOW_LIVE=1`. E2E tests require `GFLOW_CLI_E2E_PROFILE`.
+
+## Code style
+
+- 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–15). 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
+
+- Branch naming: `feature/`, `bugfix/`, `hotfix/`, `chore/`, `docs/`, `test/`, `release/` — never `claude/` or unprefixed.
+- `develop` is the integration branch; `main` is protected. Releases tag off `main` only.
+- **Never add AI attribution to commit messages.** `Co-Authored-By:` trailers are fine if the user asks for them; auto-generated "🤖 Generated with Claude Code" footers are not.
+- 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.
+
+## 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`
+- **Release protocol** → [RELEASE.md](RELEASE.md)
+
+## Claude Code-specific notes
+
+[CLAUDE.md](CLAUDE.md) carries the auto-load instructions Claude Code reads natively. It cross-references this file for the universal rules; Claude-Code-specific session protocol (skills, slash commands, memory) stays in CLAUDE.md.