roboco/docs/rag/standards/markdown-reflow-quality-gate.md

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:

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:

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:

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:

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:

# 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):

python3 scripts/reflow_md.py --diff

To auto-reflow a file in-place:

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)