Skip to content

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

Merged
MattJackson merged 2 commits into
mainfrom
ci/public-hygiene-green
Aug 9, 2026
Merged

ci: make public-hygiene-lint green#6
MattJackson merged 2 commits 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: the sentences already state what the self-test does, so
    the id is simply dropped.
  • tests/e2e.rs, tests/full_stack_e2e.rs [mutation-testing] named an internal QA harness as the
    example of a build invocation that does not uplift the cdylib. REWRITTEN to describe the build
    shape itself (a plain cargo test with no prior --all-targets/--lib build), which is the
    fact the helper actually depends on.

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 16 file(s) via git ls-files; 11 rules applied

  [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).

  [mutation-testing] mutation-testing workflow leaked into shipped prose - 3 hit(s)
      why: names an internal QA tool and the campaign it was run in; the shipped comment should state the invariant the test protects, not the harness that found the gap
      tests/e2e.rs:113: /// (exactly what `cargo mutants`'s default build step runs, and what a developer running `cargo
      tests/e2e.rs:118: /// `cargo test` invocation `cargo-mutants` uses left `profile_dir` empty while `profile_dir/deps`
      tests/full_stack_e2e.rs:107: /// doc comment for the full story: a bare `cargo test` (what `cargo-mutants` runs, and what a

== result ==
  16 public file(s) scanned against 11 rules - 5 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 16 file(s) via git ls-files; 11 rules applied

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

Matthew Jackson added 2 commits August 8, 2026 16:00
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.
full_stack_e2e asserted that one real request produces exactly one webhook
call. Against busbar 1.5.3 it produces four. That is a documented breaking
change, not a regression:

  busbarAI CHANGELOG.md, "[1.5.3] Breaking changes":
    "A hand-written hook with no stage list now fires at all four stages
     rather than once per request; set `phase: [request]` for the old
     behaviour."

The test registered its tap over the admin API with no stage scoping, so it
was getting the new all-stages fan-out: the stage-less request envelope plus
`stage.at` of candidate, routing and response. The assertion was encoding the
pre-1.5.3 default, not a property of this plugin.

This repo's `.busbar-ref` already pins 1.5.3, so the suite was asserting a
contract the core it releases against had already retired.

stage_fanout_e2e is a new file rather than more cases in full_stack_e2e: the
fan-out is its own contract and deserves to be readable on its own.
@MattJackson
MattJackson merged commit c5fd7c1 into main Aug 9, 2026
1 check passed
@MattJackson
MattJackson deleted the ci/public-hygiene-green branch August 9, 2026 00:21
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