Seven Pre-Existing Defects in GOVERNANCE.md "Verification Discipline"

[ptr727]

Seven defects in GOVERNANCE.md "Verification Discipline", found by a full-content pass over that unit during #1148 and deliberately not fixed there. That PR introduced one bullet in this section, and its own findings were fixed in it. These seven predate it, each is a fleet-law edit that ~20 carrying repositories would take, and folding them into a PR about a review gate would have put unrelated rule changes behind that PR's review.

Each was measured on a Linux host with the repo's own tooling unless noted.

1. The heredoc rule names a construct that does not have the failure

Never edit source through a shell heredoc when the text carries backslash escapes. The shell consumes the escape and writes an invisible control character in its place, so a \b inside a regex becomes a backspace

Measured false. Both cat > f <<EOF and cat > f <<"EOF" write \ and b literally, confirmed with od -c. Bash processes a backslash in an unquoted heredoc only before $, a backtick, \ and a newline. The constructs that actually do consume it are printf "...\b...", POSIX sh's builtin echo, echo -e, and $'...', none of which the rule names. So the rule bans a safe construct and leaves the unsafe ones unmentioned.

2. Path.read_text(newline=...) is 3.13 or newer

Pass newline='' to both, or work in bytes.

Path.read_text() gained newline only in 3.13; write_text() has had it since 3.10. On a 3.11 interpreter the instruction raises TypeError: Path.read_text() got an unexpected keyword argument 'newline'. spec/host-tools.json calls its 3.13 floor a target rather than a measured one and describes lower interpreters as unverified rather than known broken, so a carrier can reasonably be below it.

3. The text-mode round-trip claim is platform-dependent but stated absolutely

Path.read_text() decodes through universal newlines and write_text() writes \n back, so a read-edit-write round trip flattens the whole file

With newline=None the write translates \n to os.linesep, so on Windows the same round trip does the mirror corruption, turning an LF file into CRLF, rather than flattening. This section's own "Platform-specific code is verified only on the platform it runs on" bullet is the rule the sentence breaks.

4. The check-location rule depends on a heading no carrier is guaranteed to hold

The checks are read from what the repository declares, meaning its OPERATIONS.md "Local Verification" section

spec/files.json declares { "path": "OPERATIONS.md", "appliesTo": "*" } with no sections list, so the audit checks presence only, which spec/section-model.md states directly. TODO.md still carries "Carry the Local Verification heading into every repository's OPERATIONS.md" as open work. The bullet asserts that "finding the check never depends on how well one repository worded a pointer to it" while giving no fallback for a repo whose OPERATIONS.md has no such heading.

5. str.isprintable() needs its whitespace exemption stated

When a check inspects text for control characters, use str.isprintable() rather than a codepoint floor

'\n'.isprintable() and '\t'.isprintable() are both false, so applied to multi-line text this flags essentially every file. The repo's own use in scripts/tests/test_prose_lint.py is on short single-line tokens, where it is correct. The rule as worded omits the scope that makes it usable.

6. The contents-API recipe reproduces the empty read it warns about

content=$(gh api "repos/<owner>/<repo>/contents/<path>?ref=<ref>" --jq '.content') && printf '%s' "$content" | base64 -d

For a blob over 1 MB the contents API returns content: "" with encoding: "none". The call succeeds, so the && guard passes, and the decode produces nothing, which is exactly the "misreading a failed fetch as a successful empty read" the same sentence exists to prevent. Documented API behavior rather than measured here, and no fleet file is currently over the limit, but the rule is written generally. A size or encoding check, or gh api .../git/blobs, would close it.

7. The section's opening absolute is falsified by its own later content

every failure below is green. ... No linter, status check, or review layer catches any of them.

Two capture points described in this same section now catch one of the failures below it mechanically: .husky/pre-push since #1125, and, for the canonical-unit half, a required pull request check in the hub's own validate action since #1148. The framing was accurate when written and is not now.

Note on how these were found

A subagent read the unit whole, as a repository carrying it for the first time would, which is the pass #1138 exists to move into this repository. Seven of its fourteen findings were about content #1148 introduced and were fixed there; these seven are the rest. That split is itself evidence for the mechanism: the same read produced both, and only one half had a home in the PR that triggered it.