spec/audit.py: _code_view drops a folded-scalar body, so requireTokensInJob cannot see a token in the `if: >-` shape GOVERNANCE mandates

[ptr727]

Found resyncing ptr727/PlexCleaner against hub f3b4cc9 (audit run 2026-08-30T21:49:58Z). Nothing in this issue is a defect in PlexCleaner.

Summary

spec/audit.py's _code_view() drops the body of every block scalar, including a folded one. check_interface()'s requireTokensInJob then scans a job block that no longer contains the condition, so a token written on the continuation line of an if: >- is invisible to it.

That shape is not incidental. It is what the fleet's own style rules mandate:

• GOVERNANCE.md:229 — "multi-line if: uses folded scalar if: >- so YAML preserves whitespace correctly"
• WORKFLOW.md:36 — "Conditionals. Multi-line if: uses the folded scalar if: >-"

So a repo that follows the style rule and satisfies the contract is reported as violating the contract, while a repo that violates the style rule by inlining the expression passes.

Reproduction

Two job blocks differing only in the if: shape, both satisfying publish-release.yml's requireTokensInJob for publish:

import importlib.util, sys
sys.path.insert(0, "spec")
spec = importlib.util.spec_from_file_location("audit", "spec/audit.py")
m = importlib.util.module_from_spec(spec); spec.loader.exec_module(m)

TOKEN = "needs.validate.result == 'success'"
folded = """jobs:

  publish:
    name: Publish project release job
    needs: [plan, validate]
    if: >-
      ${{ needs.plan.outputs.publish == 'true' && needs.validate.result == 'success' }}
    uses: ./x.yml
"""
inline = folded.replace(
    "    if: >-\n      ${{", "    if: ${{"
).replace(" }}\n    uses:", " }}\n    uses:")

for label, text in (("folded", folded), ("inline", inline)):
    blk = m._code_view(m.split_jobs(text)["publish"])
    print(label, "->", TOKEN in blk)

folded -> False
inline -> True

What _code_view() leaves for the folded case:

  publish:
    name: Publish project release job
    needs: [plan, validate]
    if: >-
    uses: ./x.yml

Who this hits today

Two repos, and they are precisely the two that have adopted the hub release chain and written the condition as documented:

Repo	Ref	Token in file	Audit says
PhotoCleaner	main	present, folded	missing required 'needs.validate.result == 'success''
PlexCleaner	develop	present, folded	same

The same finding text appears against seven more repos (LanguageTags, ESPHome-NonRoot, VSCode-Server-DotNetCore, KiCadLibrary, MediaTools, Vantage-Config, Blog), but I checked each and those are true findings: the token is genuinely absent because they have not adopted the release chain. Only the two above are false positives. That ratio is the concerning part, since the false positives land on the repos that did the work.

Why the current behavior exists

The docstring is explicit, and the reasoning is sound for what it was written against:

A block-scalar string value (name: | followed by indented text) can hide or fake a token the same way, so its body is dropped too, keeping only the key: line itself (#949).

A run: or name: body is a string value, and dropping it is right. An if: body is a condition, which is exactly the structure requireTokensInJob exists to assert. _BLOCK_SCALAR_KEY does not distinguish them.

Possible directions

Not a recommendation, since the trade-off is yours:

1. Exempt if: (and any other structural key) from the block-scalar drop, keeping the body for run:, name:, and other string values. Narrow, and preserves check_interface()'s token matching reads YAML block-scalar content as structure #949's intent.
2. Fold the scalar before scanning rather than dropping it, so if: >- plus its body reads as the single logical line YAML says it is.
3. Leave _code_view() alone and have requireTokensInJob scan a YAML-parsed value for the named key instead of a text view.

Option 1 or 2 would clear the false positives without weakening the #949 guard, since neither restores a name:/run: body to the scan.

Not filed here

PlexCleaner's own convergence issue is separate. No audit report or registry change is being written back to this repo.

[ptr727]

Carried forward from #1402, closed as a duplicate of this issue. That issue found the same defect independently during the 2.0.577 resync pilot (audit run 2026-09-07T02:37:02Z | hub f8e7491), against PlexCleaner's publish-release.yml, where the condition is present and correct at both main and develop, byte-identical, in the folded form. Two things it adds:

The defect recurred as real work. The false finding was carried into that resync as a work item before being checked. That is the cost this issue names: a false positive on a release gate invites someone to "fix" a workflow that is not broken, and the plausible fix is to rewrite a correct condition.

spec/audit.py's self-test has no folded case, and that is why this reached a downstream repository. The current suite passes with the inline form only. Whichever of the three directions above is taken, the test suite deserves a case for each of the two if: forms, so the boundary cannot silently move back.

#1402 also framed the distinguishing fact slightly differently, and the framing is useful: it is the key, not the scalar style. if, and the other expression-bearing keys, hold a value that is always structure, where name: and run: hold a string body that really is prose. That is direction 1 above, stated as a rule rather than as an exemption list.