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: id dropped.
  • docker.yml, release.yml, Dockerfile, docker-compose.yml, docker/bundle/Dockerfile x7
    [commit-hash-citation] cited bare hashes. REWRITTEN: the quoted CHANGE TITLE is kept where it
    exists ("Port headroom-hook to busbar's signed dlopen plugin ABI") and the hash is dropped; the
    two references to a busbarAI hash are replaced by what that change did.
  • docker-bundle.yml, docker.yml x2, Dockerfile [authoring-meta] narrated the authoring
    transaction ("not made unilaterally here", "the agent that authored this file"). REWRITTEN to
    state the resulting STATUS: which options are still open, and that the push step is only
    exercised by a real tagged run.
  • docker-bundle.yml, release.yml x4 [machine-path] shipped a developer home directory, in prose
    AND in a live sed command. REWRITTEN, and this one is a real behaviour fix rather than a
    wording change: this repo's Cargo.toml already declares SIBLING-RELATIVE path dependencies
    (../busbarAI/crates/...), so the sed rewrite of an absolute path had become a no-op. Both
    steps are replaced by the assertion the sed step's own trailing grep was already making,
    which is the part that protects the job. Both workflows still parse.

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

  [authoring-meta] meta-commentary on how the change was authored - 4 hit(s)
      why: narrates the authoring transaction (who asked, what was in scope, who decides); a shipped file should carry no evidence that it was commissioned at all
      .github/workflows/docker-bundle.yml:39: # it; it was not (and cannot be) exercised by the agent that authored this file.
      .github/workflows/docker.yml:10: # image work) or retire it entirely is a product call, not made unilaterally here.
      .github/workflows/docker.yml:29: # for a human, not made unilaterally here.
      Dockerfile:21: # dlopen sidecar loader) or should simply be deleted is a product call for a human to

  [commit-hash-citation] bare commit-hash citation in prose - 7 hit(s)
      why: a hash resolves only against history the reader does not have; name the behaviour or the release instead
      .github/workflows/docker-bundle.yml:18: # responsibility moved to this repo (see busbarAI commit ed61aae "ci/docker: stop bundling
      .github/workflows/docker.yml:1: # STALE since "Port headroom-hook to busbar's signed dlopen plugin ABI" (commit c37b798): this
      .github/workflows/docker.yml:18: # ABI" (commit c37b798) this crate is `crate-type = ["cdylib", "rlib"]` only (no `[[bin]]`, no
      .github/workflows/release.yml:13: # Since "Port headroom-hook to busbar's signed dlopen plugin ABI" (commit c37b798) this crate is
      Dockerfile:5: # headroom-hook to busbar's signed dlopen plugin ABI" (commit c37b798), this crate
      docker-compose.yml:6: # busbar's signed dlopen plugin ABI" (commit c37b798): the plugin is now an in-process
      docker/bundle/Dockerfile:60: # before that responsibility moved to this repo; see busbarAI commit ed61aae's parent for the

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

  [machine-path] a developer home directory - 4 hit(s)
      why: an absolute path under a personal home directory names a person AND a machine, and two public workflows shipped one
      .github/workflows/docker-bundle.yml:100: # as an ABSOLUTE local path (/Users/matthew/Developer/busbarAI/busbarAI/crates/...) - a
      .github/workflows/docker-bundle.yml:111: sed -i.bak 's#/Users/matthew/Developer/busbarAI/busbarAI/crates#../busbarAI/crates#g' headroom-hook/Cargo.toml
      .github/workflows/release.yml:114: # (/Users/matthew/Developer/busbarAI/busbarAI/crates/...) - a stopgap the crate's own
      .github/workflows/release.yml:122: sed -i.bak 's#/Users/matthew/Developer/busbarAI/busbarAI/crates#../busbarAI/crates#g' headroom-hook/Cargo.toml

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

== result ==
  39 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.
`cargo build --all-targets` has been failing outright, so no test in this repo
has run at all:

  error[E0063]: missing fields `request_id` and `signals` in initializer of
                `RoutingRequest<'_>`
  error[E0063]: missing field `signals` in initializer of `Candidate<'_>`

`RoutingRequest` gained `request_id` (a per-request correlation id stamped once
at ingress) and both projections gained a `SignalBag`, in the signal-catalog
work that shipped in busbar 1.5.3. This repo's `.busbar-ref` already pins 1.5.3,
so these fixtures were building a shape the engine no longer hands a hook —
against the very core this plugin releases against.

The fixtures now supply both. `request_id` is a fixed constant because nothing
in the headroom policy reads it and a stable value keeps two otherwise-identical
requests comparable. `signals` is the empty bag, which is what the engine really
passes here: it only populates the bag for signals a hook has asked for, and
this policy asks for none.
@MattJackson
MattJackson merged commit 46379f9 into main Aug 9, 2026
1 check passed
@MattJackson
MattJackson deleted the ci/public-hygiene-green branch August 9, 2026 01:57
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