[luoye-cpu]

Summary

Issue #3353, step 1: the badge group comments move from standalone lines to trailing comments, so the header badge block renders as one band again. A line that starts with <!-- opens a CommonMark HTML block that interrupts the badge paragraph — every adopted README following the standard rendered its header as one centred row per group. In the README.md exemplar each group comment now trails the first badge line of its own group (the banner line for the first group), no line of the block starts with an HTML-comment opener, and docs/README-STANDARD.md prescribes that shape with the reason. Per the issue's split, the Praetor README-01 audit condition (step 2, internal/readmepresentation/audit.go) and the adopted-README sweep (step 3) stay with their own repos and follow once the standard lands.

Type

• feat — new feature
• fix — bug fix
• perf — performance improvement
• refactor — no behavior change
• docs — documentation only
• test — test-only
• build / ci — tooling / infra
• port — cherry-pick from upstream Netflix/vmaf
• sycl / cuda / simd — backend-specific

Checklist

• Commits follow Conventional Commits (the commit-msg hook enforces this).
• Every commit is signed off (git commit -s; fix a branch with git rebase --signoff origin/master). See DCO sign-off.
• make format && make lint is green locally — the two touched files are Markdown; the docs lane that covers them (scripts/docs/check_doc_links.py) passes: 0 findings on the touched pages' links, and no link targets changed.
• Unit tests pass — not applicable: no C/C++/build change; the README presentation audit lives in the Praetor repository (issue step 2) and cannot run against this tree.
• If I touched any SIMD/GPU code path, I ran /cross-backend-diff and the worst ULP is ≤ 2. — not applicable: two Markdown files only.
• If I touched a feature extractor with SIMD/GPU twins, I either updated every twin or listed the gap under "Known follow-ups" below. — not applicable.
• If I added a new .c / .cpp / .cu / .h / .hpp, it has the appropriate license header (see CONTRIBUTING.md). — not applicable: no new files.
• If this is a breaking change, the commit message uses ! or BREAKING CHANGE: and the migration path is documented below. — not a breaking change.
• If this PR adds an ADR, the ADR row lives in docs/adr/_index_fragments/<NNNN-slug>.md and nothing else is touched for the index: do not edit docs/adr/README.md, docs/adr/by-tag/, docs/adr/titles.md or _order.txt (rendered when pull requests land by make docs-render; see ADR-2197; the render-only pull request of ADR-3295 is the one exception). — no ADR added.

Bug-status hygiene (ADR-0165)

• docs/state.md updated in this PR with a row
  in the appropriate section (Open / Recently closed / Confirmed
  not-affected / Deferred), OR the opt-out line described in the comment above. — no state delta: badge-block layout in two Markdown files; no product behaviour, score or gate changes.

Netflix golden-data gate (ADR-0024)

• I did not modify any assertAlmostEqual(...) score in the Netflix golden Python tests, except by porting Netflix's own updated assertion verbatim from upstream (value and places as upstream has them, measured against the fork's CPU build first; ADR-1828). — not applicable: python/test/ untouched.
• If I believe a golden value must change, I have explained why below AND pinged @lusoris for a CODEOWNERS exception. — not applicable: no golden value touched.

Deep-dive deliverables (ADR-0108)

• Research digest — no digest needed: the issue is the analysis (the CommonMark HTML-block-interrupts-paragraph mechanism, the GitHub Markdown API evidence, and the prescribed trailing form).
• Decision matrix — no alternatives to weigh: the issue prescribes the trailing-comment shape ("at the end of the last badge line of the group before it, or at the end of the first badge line of its own group"); this PR applies the own-group form, which keeps each comment visually attached to the group it names.
• AGENTS.md invariant note — none added: two Markdown content files carry no rebase-sensitive invariant.
• Reproducer / smoke-test command — pasted below under "Reproducer".
• CHANGELOG fragment — no changelog entry needed: the rendered README header's HTML shape is not a changelog-worthy behaviour change; the standard page itself documents the rule.
• Rebase note — no rebase impact: two Markdown files; a conflict resolves by keeping both the trailing-comment shape and the prescribed text.

Reproducer

grep -nE '^\s*<!-- [0-9]' README.md        # no standalone group-comment lines remain
grep -c '<!-- [0-9] [a-z/]* -->$' README.md # every group comment trails a badge line
sed -n '78,86p' docs/README-STANDARD.md     # the standard prescribes the trailing shape and the reason

Known follow-ups

• Praetor README-01 (internal/readmepresentation/audit.go): add the one-paragraph condition with the planted per-line case — issue step 2, Praetor repository.
• The README sweep for every adopted README (issue step 3) runs once this standard lands.
• golusoris/.github pull request 10 keeps its current layout until the standard lands (the issue's out-of-scope note).

Part of #3353 (deliberately not Closes: steps 2 and 3 live outside this repository).

Summary by Sourcery

Preserve a single-band README badge layout by adopting trailing group comments in the exemplar and standard.

Enhancements:

• Keep the README badge block rendering as a single centred band by placing group comments as trailing comments on badge lines.
• Update the README standard to require trailing group comments and document the CommonMark rendering rationale.

Documentation:

• Document the required trailing-comment format for README badge groups.

Summary by CodeRabbit

• Documentation
  • Updated the README badge layout so the groups appear together in one centered band; badge links and displayed values are unchanged.
  • Clarified the badge formatting guidance, including how comment placement affects whether badge groups appear in one band or separate rows.

[sourcery-ai]

Reviewer's Guide

Documentation

Move the README badge-group comments onto badge lines to preserve one continuous rendered band, and document the CommonMark constraint and required format in the standard.

• README.md L8-10, L17, L22-26
• docs/README-STANDARD.md L78-83

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[coderabbitai]

No actionable comments were generated in the recent review.

Walkthrough

The README badge group comments moved inline onto the badges. The README standard now explains that standalone comments split the badge block into separate centered rows.

Changes: Badge block formatting

Layer / File(s)	Summary
Inline badge group comments README.md, docs/README-STANDARD.md	The README moves the group comments onto the corresponding badges without changing the badge set, order, labels, or destinations. The guidance explains that standalone comments split the badge block into separate centered rows.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Change: Other · Severity of issue fixed: Low

Possibly related issues

• Issue 3353 describes the same behavior: standalone badge-group comments split the badge block into separate paragraphs. The README and its standard now address this behavior.

Suggested labels: type:docs

Merge Risk: Minimal · up to 25f97

The change adjusts badge annotations and guidance; no merge-blocking risk is established.

Architecture risk: Low · up to 25f97

The change affects 2 systems.

Changed systems: docs, README.md

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

• observed — docs (service) was modified; 1 changed file maps to changed impact.
• observed — README.md (service) was modified; 1 changed file maps to changed impact.

Before / after behavior

• observed — Modified behavior in README.md: The README badge block changes its grouping annotation from “one group” to “one band” and moves the numbered group labels inline onto their corresponding badges. The badge set, order, labels, and destinations are unchanged.
• observed — Modified behavior in docs/README-STANDARD.md: The Badge block guidance moves each group’s order-checking comment from an introductory standalone line to the first badge line of its group (or the banner line for the first group). It also states that a standalone comment interrupts the badge paragraph, producing separate centered rows instead of one band.

Pre-merge checks: 4

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly describes the badge-block formatting change and its purpose: keeping the badges in one band with trailing group comments.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Finishing Touches

Generate unit tests (beta)

• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Recent review info

Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: c91e9a8c-9ff8-480b-987a-488a4b75b31d

Commits

Reviewing files that changed from the base of the PR and between 5c94107 and 25f9776.

Files selected for processing: 2

• README.md
• docs/README-STANDARD.md

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 7 remain after this review.

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

AI Reviewer: first review requested successfully. AI can make mistakes. Always validate suggestions.

_{TIP This summary will be updated as you push new changes.}

[codacy-production]

Pull Request Overview

⚠️ Resolve issues before merging

The release badge line must retain its update marker as the final comment; placing the group comment after it may break release automation and verification. This should be corrected before merging.

The documented invariants currently have no automated coverage, so the badge ordering and formatting should be validated with repository checks or focused tests.

About this PR

• Add automated checks for the README badge-group formatting invariants to prevent regressions.

Test suggestions

• Verify README contains no standalone numbered group-comment lines.
• Verify all six group comments trail the intended banner or badge lines and preserve group order.
• Verify the standard documentation contains the trailing-comment rule and CommonMark rendering rationale.

Prompt proposal for missing tests

Consider implementing these tests if applicable:
1. Verify README contains no standalone numbered group-comment lines.
2. Verify all six group comments trail the intended banner or badge lines and preserve group order.
3. Verify the standard documentation contains the trailing-comment rule and CommonMark rendering rationale.

_{TIP How was this review? Give us feedback}

[codacy-production]

_{🟡 MEDIUM RISK}

Move <!-- 2 CI/build --> to the first CI badge line, leaving <!-- x-release-please-version --> as the final comment on the release line.

_{TIP React 👍 if this review is right, or reply with what's wrong and how it could be better to help improve the reviewer.}

[sourcery-ai]

Hey - I've found 2 issues

Prompt for AI Agents

Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="README.md" line_range="10" />
<code_context>
-  <!-- 1 release/version -->
-  [![Release](https://img.shields.io/static/v1?label=release&message=v1.0.0-rc.3&style=for-the-badge&color=3b82f6&labelColor=111a35)](https://github.com/VMAFx/vmafx/releases) <!-- x-release-please-version -->
-  <!-- 2 CI/build -->
+  [![Release](https://img.shields.io/static/v1?label=release&message=v1.0.0-rc.3&style=for-the-badge&color=3b82f6&labelColor=111a35)](https://github.com/VMAFx/vmafx/releases) <!-- x-release-please-version --> <!-- 2 CI/build -->
   [![Tests](https://github.com/VMAFx/vmafx/actions/workflows/tests-and-quality-gates.yml/badge.svg?branch=master&event=push)](https://github.com/VMAFx/vmafx/actions/workflows/tests-and-quality-gates.yml)
   [![Builds](https://github.com/VMAFx/vmafx/actions/workflows/libvmaf-build-matrix.yml/badge.svg?branch=master&event=push)](https://github.com/VMAFx/vmafx/actions/workflows/libvmaf-build-matrix.yml)
</code_context>
<issue_to_address>
**Release badge version stays stale**

When release-please updates the README for a version bump, the `<!-- 2 CI/build -->` marker follows the `x-release-please-version` marker, so release-please no longer finds the version marker at the end of the badge line and leaves the displayed release version stale. The group marker also appears after the Release badge instead of the first CI badge, so it labels the wrong group.

Move `<!-- 2 CI/build -->` after the Tests badge, leaving `<!-- x-release-please-version -->` at the end of the Release badge line.

Also at `README.md:11`.
</issue_to_address>

### Comment 2
<location path="docs/README-STANDARD.md" line_range="78-83" />
<code_context>

-Each group is introduced by an HTML comment (`<!-- 2 CI/build -->`) so a
-reviewer can check the order without rendering the page.
+Each group carries an HTML comment (`<!-- 2 CI/build -->`) so a reviewer can
+check the order without rendering the page. The comment trails the first badge
+line of its own group (the banner line for the first group) and never starts a
+line of its own: a line that begins with `<!--` opens a CommonMark HTML block
+that interrupts the badge paragraph, and the block then renders as one centred
+row per group instead of one band.

 Version badges for languages, toolchains, backends and integrations (C, Go,
</code_context>
<issue_to_address>
**Rendering rationale lacks evidence**

The new paragraph asserts that standalone comments interrupt the badge paragraph and produce separate rows but links no specification, GitHub evidence, or tracked reproducer, so readers cannot verify the documented rendering rule.

Link the relevant CommonMark or GitHub rendering evidence, or add a tracked reproducer for the claim.
</issue_to_address>

Sourcery assessment

Approval pending. 1 finding to address first.

Blocking findings: README.md:10

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

[sourcery-ai]

🟡 Medium · Release badge version stays stale

When release-please updates the README for a version bump, the <!-- 2 CI/build --> marker follows the x-release-please-version marker, so release-please no longer finds the version marker at the end of the badge line and leaves the displayed release version stale. The group marker also appears after the Release badge instead of the first CI badge, so it labels the wrong group.

Move <!-- 2 CI/build --> after the Tests badge, leaving <!-- x-release-please-version --> at the end of the Release badge line.

Also at README.md:11.

Prompt for AI agents

In `README.md` at line 10:

**Release badge version stays stale**

When release-please updates the README for a version bump, the `<!-- 2 CI/build -->` marker follows the `x-release-please-version` marker, so release-please no longer finds the version marker at the end of the badge line and leaves the displayed release version stale. The group marker also appears after the Release badge instead of the first CI badge, so it labels the wrong group.

Move `<!-- 2 CI/build -->` after the Tests badge, leaving `<!-- x-release-please-version -->` at the end of the Release badge line.

Also at `README.md:11`.

[sourcery-ai]

⚪ Low · Rendering rationale lacks evidence

The new paragraph asserts that standalone comments interrupt the badge paragraph and produce separate rows but links no specification, GitHub evidence, or tracked reproducer, so readers cannot verify the documented rendering rule.

Link the relevant CommonMark or GitHub rendering evidence, or add a tracked reproducer for the claim.

Prompt for AI agents

In `docs/README-STANDARD.md` at lines 78-83:

**Rendering rationale lacks evidence**

The new paragraph asserts that standalone comments interrupt the badge paragraph and produce separate rows but links no specification, GitHub evidence, or tracked reproducer, so readers cannot verify the documented rendering rule.

Link the relevant CommonMark or GitHub rendering evidence, or add a tracked reproducer for the claim.

From docs/principles.md L934-939:

- **C core:** rules 5 and 10 adapt to reference, rendering and diagnostic
  validation. Other C-core rules apply to executable examples, not prose.
- **Additions:** `docs/`, root Markdown and [python/README.rst](../python/README.rst)
  document behavior with reproducible commands and tracked evidence links.
  Keep examples consistent with their implementation language; rendered
  tables, equations and diagrams must remain usable without script execution.

[lusoris]

Requesting changes for two findings in the badge block. Folding the group comments into the badge lines does what this PR sets out to do: the header renders as one band instead of one row per group.

What I checked on head 25f9776:

• Rendering: cmark turns the header into 4 paragraphs, where master gives 8, so the badges now share one band.
• Releases: release-please's generic updater replaces only the first version string on a line marked x-release-please-version (its pattern is not global), so the extra comment on the Release line does not change what a release rewrites.
• Order check: with the labels 1 release/version and 2 CI/build swapped on this head, Praetor's README-01 check reports no order finding. The same swap on master is reported. Both inline comments explain why and give a layout that restores the check.

Conflict: #3393 also edits the badge block in README.md and the "Badge block" section of docs/README-STANDARD.md. Whichever of the two lands second needs a merge from master, resolved inside the conflict markers.

[lusoris]

Required: <!-- 2 CI/build --> trails the Release badge, which belongs to group 1. The rule this PR adds to docs/README-STANDARD.md says the comment trails the first badge line of its own group, so this comment belongs on the Tests line below:

  [![Release](...)](...) <!-- x-release-please-version -->
  [![Tests](...)](...) <!-- 2 CI/build -->

[lusoris]

Required: Praetor's README-01 order check reads only the first HTML comment on a line. Here that is the README-STANDARD badge block note, so the 1 release/version label is never read, and on the Release line the first comment is x-release-please-version. On this head the check finds no group labels at all, which is why a swapped order passes.

Putting the group label first fixes it without changing the rendered page:

  <img ... /> <!-- 1 release/version --> <!-- README-STANDARD badge block: one band, fixed group order (docs/README-STANDARD.md) -->

With that change and the Tests-line move from the other comment, I ran the check again: it reads groups 1 and 2 in order, reports the planted swap, and reports nothing new on the unswapped page. The cmark output is the same as on this head. A sentence in docs/README-STANDARD.md saying the group label comes before any other comment on its line would keep the next edit from undoing this.