roboco-app[bot]GitHubBackend Developer 2Backend Documenterroboco-app[bot] <302741806+roboco-app[bot]@users.noreply.github.com>Backend Developer 1roboco-app[bot] <302741806+roboco-app[bot]@users.noreply.github.com>roboco-app[bot] <302741806+roboco-app[bot]@users.noreply.github.com>* [c2d8f8fa] Write Port AI Builder competitive-positioning doc (#722) * [c2d8f8fa] docs(backend): add Port AI Builder competitive-positioning analysis * [c2d8f8fa] docs(backend): fix all wrong file:line citations in Port AI Builder positioning doc --------- Co-authored-by: Backend Developer 1 <be-dev-1@roboco.tech> * [c232e514] Fix PR #755 review findings: wording accuracy + branch staleness (#784) * [4815da95] docs(analysis): fix pr_gate wording findings on CEO-check scope and conventions default (#776) Co-authored-by: Backend Developer 1 <be-dev-1@roboco.tech> * [c0c2ac32] Resolve CI blocker F-397f9453 on PR #784 head (#791) * [c0c2ac32] fix(docs): reflow hard-wrapped prose in competitive-positioning doc to pass quality gate * [c0c2ac32] docs(qa): add CI fix note for reflow-check on competitive positioning doc --------- Co-authored-by: Backend Developer 2 <be-dev-2@roboco.tech> Co-authored-by: Backend Documenter <be-doc@roboco.tech> * [26e8731d] Sync branch and resolve pr_gate CI blocker 397f9453 on PR #784 head (#788) * [26e8731d] Document CI staleness pattern in lifecycle artifacts script docstring * [26e8731d] Remove false docstring claiming docs/ is outside CI paths filter The docstring at lines 13-15 claimed docs/ is outside the CI workflow's paths filter, making doc-only commits not trigger CI. This is false — ci.yml lists docs/** at line 44 (push) and line 83 (pull_request). The stale-CI diagnosis built on this false premise is incorrect. Removing the false note per finding F-000d3430. * [26e8731d] docs(contributing): list markdown reflow check in make quality gate description CONTRIBUTING.md's make quality comment listed only 4 checks (ruff format, ruff check, mypy, pytest) but the Makefile quality target runs 8+ including the markdown prose reflow check (scripts/reflow_md.py --check). That omission directly contributed to the CI blocker this task investigated — a contributor reading the old comment would not expect the reflow gate. Added the reflow check to the comment list and a note pointing to make reflow-docs as the auto-fix and docs/rag/standards/markdown-reflow-quality-gate.md for the standard. --------- Co-authored-by: Backend Developer 2 <be-dev-2@roboco.tech> Co-authored-by: Backend Documenter <be-doc@roboco.tech> --------- Co-authored-by: roboco-app[bot] <302741806+roboco-app[bot]@users.noreply.github.com> Co-authored-by: Backend Developer 1 <be-dev-1@roboco.tech> Co-authored-by: Backend Developer 2 <be-dev-2@roboco.tech> Co-authored-by: Backend Documenter <be-doc@roboco.tech> * [f4529578] Reflow CONTRIBUTING.md blockquote to clear reflow-check CI failure on PR #755 (#800) * [f4529578] reflow(contributing): join 3-line blockquote and strip line 31 indent to clear reflow-check * [f4529578] docs(changelog): note CONTRIBUTING.md reflow fix that cleared reflow-check CI gate * [f4529578] docs(changelog): clarify reflow fix unblocks competitive-positioning PR #755 * [f4529578] docs(changelog): add reflow-passthrough detail to CONTRIBUTING.md fix note * [f4529578] docs(changelog): add task ID reference to CONTRIBUTING.md reflow fix entry * [f4529578] docs(changelog): add exact reflow-check exit output to CONTRIBUTING.md fix entry * [12b3bce9] fix(contributing): join blockquote and remove indent to clear reflow-check CI failure (#799) Co-authored-by: Backend Developer 1 <be-dev-1@roboco.tech> --------- Co-authored-by: Backend Developer 1 <be-dev-1@roboco.tech> Co-authored-by: Backend Documenter <be-doc@roboco.tech> Co-authored-by: roboco-app[bot] <302741806+roboco-app[bot]@users.noreply.github.com> --------- Co-authored-by: roboco-app[bot] <302741806+roboco-app[bot]@users.noreply.github.com> Co-authored-by: Backend Developer 1 <be-dev-1@roboco.tech> Co-authored-by: Backend Developer 2 <be-dev-2@roboco.tech> Co-authored-by: Backend Documenter <be-doc@roboco.tech>
2.4 KiB
CI Fix: Reflow-Check on Competitive Positioning Doc
PR #784 / PR #791 — Resolved
Root Cause
The Python quality gate's reflow-check step was failing on docs/backend/analysis/port-ai-builder-competitive-positioning.md. The doc contained hard-wrapped markdown prose (manual line breaks within paragraphs), which the reflow-check rejects — it requires one line per paragraph so that diffs stay clean and the prose reflows naturally in any viewer width.
The failure was initially suspected to be CI staleness (a prior sync_branch rebase was claimed to have resolved it), but sync_branch returned superseded — the branch was already in sync. The real cause was the hard-wrapped lines in the doc itself, not a stale CI state.
Solution Applied
Reflowed the hard-wrapped prose to one line per paragraph throughout docs/backend/analysis/port-ai-builder-competitive-positioning.md. This is a formatting-only change: no content, wording, or citations were modified. The verified wording at line 11 (require_ceo_role()) and line 37 (ROBOCO_CONVENTIONS_ENABLED) is intact.
All other quality-gate steps were already clean: ruff format, ruff check, mypy, xenon, vulture, bandit, deptry, alembic, lint-imports, compose-sync, pip-audit.
Impact
- Scope: Documentation formatting only (one markdown file)
- Risk: None — reflow only changes line wrapping, not content
- Behavior: No change to any code, tests, or doc content
- Verification: Local
make qualityrun confirmed full pass after reflow
Pattern
The reflow-check enforces one-line-per-paragraph in markdown prose files under docs/. When authoring or editing markdown docs, write each paragraph as a single long line — let the viewer handle wrapping. Do not insert manual line breaks within a paragraph.
# Correct — one line per paragraph
This is a paragraph. It can be very long, and that is fine. The reflow-check
wants each paragraph on a single line so diffs are clean and the prose
reflows naturally in any viewer width.
# Wrong — hard-wrapped prose (reflow-check fails)
This is a paragraph. It is manually wrapped
at a fixed column width, which the reflow-check
rejects because it creates noisy diffs.
If the reflow-check fails on a doc you edited, run make quality locally — the failing file and the reflow expectation will be in the output. Join the hard-wrapped lines and re-run the gate.