Skip to content

ci: make public-hygiene-lint green - #4

Merged
MattJackson merged 1 commit into
mainfrom
ci/public-hygiene-green
Aug 9, 2026
Merged

ci: make public-hygiene-lint green#4
MattJackson merged 1 commit into
mainfrom
ci/public-hygiene-green

Conversation

@MattJackson

Copy link
Copy Markdown
Contributor

public-hygiene-lint was RED on main in this repo. Every hit is fixed by rewriting the text to
state the BEHAVIOUR rather than our internal process. No allow markers were added anywhere in
this change: a blanket allow would turn the gate into decoration.

Hits found on main, and the decision for each

  • .github/scripts/next-version.sh + .github/workflows/release-selftest.yml [internal-issue-id]
    cited an internal guard id. REWRITTEN: id dropped.
  • Cargo.toml [commit-hash-citation] cited a bare commit hash for the layout this workspace
    mirrors. REWRITTEN to name the thing being mirrored (auth-oidc's same-repo workspace layout),
    which a reader can actually go and look at.

Red before green

Same invocation CI uses. Output is ASCII-folded for this description; the runs are verbatim
otherwise.

Before (on main)

$ python3 busbarAI/scripts/public-hygiene-lint.py --root .
== public-hygiene: what a customer reads, in . ==
  scanned 19 file(s) via git ls-files; 11 rules applied

  [commit-hash-citation] bare commit-hash citation in prose - 1 hit(s)
      why: a hash resolves only against history the reader does not have; name the behaviour or the release instead
      Cargo.toml:10: # (commit 1875b2f) exactly.

  [internal-issue-id] internal issue / task / audit-round identifier - 2 hit(s)
      why: cites a tracker or audit artifact the reader cannot open; `task #141` and `R27 #8` shipped inside operator-facing API documentation
      .github/scripts/next-version.sh:5: # release automation can't silently rot (guard #135.8). Prints "v<MAJOR>.<MINOR>.<PATCH>" to stdout.
      .github/workflows/release-selftest.yml:1: # CI self-test for the release-on-upstream version-compute logic (guard #135.8).

== result ==
  19 public file(s) scanned against 11 rules - 3 hit(s), 0 allowed
  public-hygiene-lint FAILED
  These lines describe how the software was BUILT, not what it does, in files a
  customer can read. Rewrite the text to state the behaviour or the invariant; if a
  line is genuinely legitimate, mark it:
    # public-hygiene-lint: allow - <why this text belongs in a public file>

After (this branch)

$ python3 busbarAI/scripts/public-hygiene-lint.py --root .
== public-hygiene: what a customer reads, in . ==
  scanned 19 file(s) via git ls-files; 11 rules applied

== result ==
  19 public file(s) scanned against 11 rules - 0 hit(s), 0 allowed
  public-hygiene-lint passed

The public-hygiene gate flags text in customer-readable files that
describes how the software was BUILT rather than what it DOES. Every hit
in this repo is rewritten to state the behaviour or the invariant; no
allow markers are added, so the gate keeps its teeth.
@MattJackson
MattJackson merged commit 311c564 into main Aug 9, 2026
2 checks passed
@MattJackson
MattJackson deleted the ci/public-hygiene-green branch August 9, 2026 00:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant