[e4ed92d6] Video pipeline per-project requests, re-render action, composition preview (#403)

* [7f2c881a] Project-scope video pipeline + re-render + preview proxy (#386) (#396) * [7f2c881a] feat(video): scope on-demand video requests + render loop to project_id Require project_id on VideoRequestBody (404 when unresolvable or not opted into the video engine), thread it through VideoEngine.open_video_task via a shared resolve_authoring_project helper, and resolve the render loop's motion/ workspace from the authoring task's own project_id instead of the hardcoded self_heal_project_slug. * [7f2c881a] fix(video): cast task.id to UUID before VideoEngine.rerender calls mypy flagged task.id as sqlalchemy.sql.sqltypes.UUID[Any] rather than uuid.UUID in the three rerender tests; cast to UUID per the codebase's established idiom (cast("UUID", obj.id)) used elsewhere for the same SQLAlchemy Mapped-attribute inference gap. * [7f2c881a] docs(video): API endpoints for project-scoped requests, re-render, and preview proxy Add comprehensive API documentation for the new project-scoped video engine endpoints: - POST /api/video/request: on-demand video authoring scoped to project_id (breaking change) - POST /api/video/pipeline/{task_id}/rerender: CEO-triggered re-render with idempotency key clearing - GET /api/video/preview/{task_id}/{file_path}: CEO preview proxy with path-traversal confinement Document project-scoping architecture: authoring tasks and render loop now resolve from task's own project_id instead of hardcoded self_heal_project_slug. Add migration guide covering breaking change to VideoRequestBody schema (project_id now required), error handling changes (404 on unresolvable/non-opted-in projects), and client migration steps. --------- Co-authored-by: Backend Developer 1 <be-dev-1@roboco.tech> Co-authored-by: Backend Documenter <be-doc@roboco.tech> * [8f959c3b] docs(ux_ui): add project picker, re-render control, and composition preview panel spec (#381) (#398) Co-authored-by: UX/UI Developer 1 <ux-dev-1@roboco.tech> * [1fb5b5cb] Project picker, re-render button, and composition preview panel (#397) (#402) * [1fb5b5cb] feat(video): project picker, re-render button, and composition preview panel * [1fb5b5cb] docs(video): add comprehensive guide for project picker, re-render button, and composition preview panel --------- Co-authored-by: Frontend Developer 1 <fe-dev-1@roboco.tech> Co-authored-by: Frontend Documenter <fe-doc@roboco.tech> * [a512f364] Add video_engine_enabled to ProjectSummaryResponse (#412) (#414) * [a512f364] feat(api): surface video_engine_enabled on ProjectSummaryResponse * [a512f364] docs(api): document video_engine_enabled on ProjectSummaryResponse --------- Co-authored-by: Backend Developer 1 <be-dev-1@roboco.tech> Co-authored-by: Backend Documenter <be-doc@roboco.tech> * [03607ab9] Fix re-render control gating/placement and project picker filter (#434) * [f2f3e89f] Fix RerenderControl gating/placement across queue and strip views (#431) * [f2f3e89f] feat(video): widen RerenderControl gating and share it across queue/strip views Extracts RerenderControl into a shared panel/src/components/dashboard/ video-rerender-control.tsx component, widens its gate from render_status === 'failed' to source_task_id + composition_id present (matching what the backend rerender endpoint actually requires), adds a confirm dialog before firing the mutation, and wires the same component into video-pipeline-strip.tsx for still-in-flight rendering/render_failed rows. * [f2f3e89f] docs(video): enhance RerenderControl JSDoc with gating logic and usage examples Add comprehensive JSDoc to the RerenderControl component covering its purpose, gating logic (render for any source_task_id + composition_id, regardless of render_status), three visual button states (idle/loading/ error), confirm-dialog guard behavior, and usage examples for both video-post-queue.tsx and video-pipeline-strip.tsx contexts. Explains why the backend's rerender endpoint doesn't require a failed render and how the component prevents accidental re-renders. --------- Co-authored-by: Frontend Developer 1 <fe-dev-1@roboco.tech> Co-authored-by: Frontend Documenter <fe-doc@roboco.tech> * [404d8ed3] Filter project picker to video-engine-enabled projects (#432) * [404d8ed3] feat(panel): filter video-request project picker to opted-in projects Add video_engine_enabled to the client ProjectSummary type, give ProjectSelector a videoEngineOnly filter prop, default RequestVideoDialog's picker to the current video-enabled project with a friendly empty-state when none exist, and cover the filter with a new project-selector test. * [404d8ed3] docs(panel): add ProjectSelector component API reference with videoEngineOnly filter Document the reusable ProjectSelector component with its props, filtering behavior, and new videoEngineOnly filter for video-engine-enabled projects. Follows the existing component documentation pattern from page-refresh-provider. --------- Co-authored-by: Frontend Developer 2 <fe-dev-2@roboco.tech> Co-authored-by: Frontend Documenter <fe-doc@roboco.tech> * [519a4088] fix(panel): import missing RerenderControl in video-post-queue and correct stale doc (#436) Co-authored-by: Frontend Developer 1 <fe-dev-1@roboco.tech> --------- Co-authored-by: Frontend Developer 1 <fe-dev-1@roboco.tech> Co-authored-by: Frontend Documenter <fe-doc@roboco.tech> Co-authored-by: Frontend Developer 2 <fe-dev-2@roboco.tech> * [8e912c3e] Reflow hard-wrapped video UX design doc to pass quality gate (#439) * [ccfe2015] docs(ux_ui): reflow video request composition-controls spec to one line per paragraph (#438) Co-authored-by: UX/UI Developer 1 <ux-dev-1@roboco.tech> * [99c3ed9c] docs(backend): reflow hard-wrapped prose in video-engine-endpoints.md and video-project-scoping.md (#442) Co-authored-by: UX/UI Developer 1 <ux-dev-1@roboco.tech> * [c2e98fc0] docs(backend): strip stray trailing whitespace in video-engine-endpoints.md fence (#451) Co-authored-by: UX/UI Developer 1 <ux-dev-1@roboco.tech> * [9c7bc11a] Reflow all 3 hard-wrapped docs on this branch and verify quality gate (#457) * [9c7bc11a] test(scripts): guard reflow_md.py --check wiring into make quality * [9c7bc11a] docs(standards): document markdown reflow quality gate workflow and verification Added comprehensive guide explaining the one-logical-unit-per-line markdown prose standard, how the reflow check integrates into make quality, the three reflowed files (video-engine-endpoints.md, video-project-scoping.md, composition-controls spec), and the regression test added to ensure wiring stability. This task verifies all three ACs are satisfied: reflow_md.py --check exits 0, make quality passes (non-DB portions), and the three files are whitespace-only reflowed. --------- Co-authored-by: UX/UI Developer 1 <ux-dev-1@roboco.tech> Co-authored-by: UX/UI Documenter <ux-doc@roboco.tech> --------- Co-authored-by: UX/UI Developer 1 <ux-dev-1@roboco.tech> Co-authored-by: UX/UI Documenter <ux-doc@roboco.tech> * [002f0cdd] docs(rag): document reflow-check zero-diff troubleshooting path (#459) (#460) Co-authored-by: Backend Developer 1 <be-dev-1@roboco.tech> * [e4ed92d6] fix rerender missing-task test — assert the empty queue it creates The test never seeds; the trailing assertion expected a phantom video post. Broken since the branch's first commit but never executed — every earlier CI run short-circuited at a pre-pytest gate step. --------- Co-authored-by: Backend Developer 1 <be-dev-1@roboco.tech> Co-authored-by: Backend Documenter <be-doc@roboco.tech> Co-authored-by: UX/UI Developer 1 <ux-dev-1@roboco.tech> Co-authored-by: Frontend Developer 1 <fe-dev-1@roboco.tech> Co-authored-by: Frontend Documenter <fe-doc@roboco.tech> Co-authored-by: Frontend Developer 2 <fe-dev-2@roboco.tech> Co-authored-by: UX/UI Documenter <ux-doc@roboco.tech> Co-authored-by: Renn F <rennf93@users.noreply.github.com>
2026-08-03 07:23:24 +02:00 · 2026-07-11 07:39:17 +02:00
parent 4d52f6ff59
commit 7f138d3bf5
29 changed files with 2707 additions and 107 deletions
@@ -0,0 +1,115 @@
+# Markdown Reflow Quality Gate
+
+## Overview
+
+The markdown reflow quality gate ensures that all documentation prose follows a strict one-sentence-per-line formatting standard, avoiding hard-wrapped text that breaks mid-clause across multiple lines. This improves diff readability, version control hygiene, and makes prose edits easier to track.
+
+## What is Hard-Wrapping?
+
+**Hard-wrapped** prose is text that is broken across multiple lines at arbitrary column boundaries for display purposes, typically to keep lines under 80-100 characters:
+
+```markdown
+This is a paragraph that has been
+hard-wrapped mid-sentence across two
+separate lines for no good reason.
+```
+
+The reflow quality gate **rejects** this pattern. Instead, prose should follow the **one-logical-unit-per-line** rule:
+
+```markdown
+This is a paragraph that has been hard-wrapped mid-sentence across two separate lines for no good reason.
+```
+
+The reflowed version is a single line, making the change history (git diff) cleaner and more readable.
+
+## The Reflow Check Script
+
+RoboCo includes a deterministic script, `scripts/reflow_md.py`, that detects hard-wrapped prose in markdown files:
+
+```bash
+python3 scripts/reflow_md.py --check
+```
+
+**Exit codes:**
+- `0`: All markdown prose in scope is reflowed (one logical unit per line)
+- `1`: Hard-wrapped prose detected; the output names affected files
+
+**Scope:** The check runs on `.md` files in tracked directories (`docs/`, `README.md`), excluding code blocks, tables, and YAML frontmatter.
+
+## Quality Gate Integration
+
+The reflow check is **wired into `make quality`**, the Python test/lint/type-check gate that all merged PRs must pass:
+
+```bash
+make quality
+```
+
+This runs (among other checks):
+1. `uv run ruff format --check .` — code formatting
+2. `uv run ruff check .` — linting
+3. `python3 scripts/reflow_md.py --check` — markdown reflow
+4. `uv run mypy roboco/ tests/` — type checking
+5. `uv run pytest` — unit tests (DB-dependent, skipped in sandboxes)
+
+A failure in *any* stage blocks the merge.
+
+## Reflowed Files (Verification Task: 9c7bc11a)
+
+The following three documentation files were reflowed to pass the quality gate:
+
+| File | Commit | Task |
+|------|--------|------|
+| `docs/backend/api/video-engine-endpoints.md` | `18bc3247` | `99c3ed9c` |
+| `docs/backend/migrations/video-project-scoping.md` | `18bc3247` | `99c3ed9c` |
+| `docs/ux_ui/design/01-video-request-composition-controls.md` | `5435a2da` | `ccfe2015` |
+
+Each file was reflowed by dedicated subtasks to eliminate all hard-wrapped prose. The diffs for these files are **whitespace-only** — no content, headings, code blocks, or tables were altered, only line breaks repositioned to match the one-logical-unit-per-line standard.
+
+## Regression Test
+
+To ensure the reflow-check wiring does not regress (e.g., if a future Makefile edit accidentally removes the check), a regression test was added:
+
+**File:** `tests/unit/scripts/test_reflow_md.py`
+
+**Tests:**
+1. `test_quality_target_wires_in_reflow_check` — Verifies that `make quality` explicitly invokes `scripts/reflow_md.py --check`.
+2. `test_check_passes_on_repo_as_committed` — Confirms the check exits 0 on HEAD.
+3. `test_check_fails_on_a_hard_wrapped_file` — Verifies the check correctly rejects hard-wrapped prose.
+
+Running `uv run pytest tests/unit/scripts/test_reflow_md.py` ensures the wiring remains intact.
+
+## How to Verify
+
+To verify that all three files are reflowed correctly:
+
+```bash
+# Run the reflow check on the entire repo
+python3 scripts/reflow_md.py --check
+
+# Expected output:
+# OK: no hard-wrapped markdown prose in scope.
+```
+
+To see which files would be reflowed by the script (without modifying them):
+
+```bash
+python3 scripts/reflow_md.py --diff
+```
+
+To auto-reflow a file in-place:
+
+```bash
+python3 scripts/reflow_md.py --fix <file>
+```
+
+## Next Steps
+
+- When editing `docs/backend/api/video-engine-endpoints.md`, `docs/backend/migrations/video-project-scoping.md`, or `docs/ux_ui/design/01-video-request-composition-controls.md`, ensure prose continues to follow the one-logical-unit-per-line standard.
+- Before committing, run `python3 scripts/reflow_md.py --check` to catch hard-wrapped prose early.
+- If a new documentation file is added, it will automatically be checked by the quality gate on the next PR.
+
+## References
+
+- Regression test: `tests/unit/scripts/test_reflow_md.py`
+- Reflow script: `scripts/reflow_md.py`
+- Quality gate: `Makefile` (see `quality` target)
@@ -103,6 +103,14 @@ escalate_to_ceo(task_id=parent_id, reason="...")
 1. Complete the blocking subtasks first (drive them through QA → docs → `complete(task_id, notes)`)
 2. Cancel them if no longer needed (PM/CEO only — cancellation is not an agent verb; ask your PM)

+## Reflow/Formatting Task Has Zero Diff
+
+**Symptom**: A task asks you to reflow specific markdown file(s) so they pass `make reflow-check`, but `python3 scripts/reflow_md.py --check` already reports "OK" with no changes, so there is no diff to commit — and `i_am_done` hard-requires at least one commit.
+
+**Cause**: `scripts/reflow_md.py` walks the whole repo tree (`ROOT.rglob("*.md")`) on every invocation; it does not scope to positional file-path arguments passed on the command line, so `--check docs/foo.md` and a bare `--check` do the same repo-wide scan. If the target file(s) were already reflowed upstream (e.g. in an earlier commit on the same branch chain), the task is satisfied-by-upstream with a structurally empty diff.
+
+**Solution**: Verify with the repo-wide check (not a scoped one, since scoping is a no-op) and record the zero-diff finding in a `decision` journal entry. If the task's acceptance criteria are already met with nothing left to change in the named files, do not keep re-running the same check — escalate once with the concrete verification so a PM can either stamp the task as satisfied-by-upstream/cancel it, or direct a small verification commit outside the target file(s) to satisfy the commit gate.
+
 ## Invalid Task Status for Operation

 **Error**: "Task is in [status], expected [expected_status]"