Put report authorship with the hub, and name the base branch - #515
Merged
Conversation
#508 arrived as a downstream repo opening a pull request against the hub to rewrite its own audit report and registry entry. Nothing forbade it, because AUDIT.md said the audit is read-only and produces a report without ever saying who writes it, so an agent filled the vacuum. The maintainer's call is that the hub owns its own reports, and the argument that settles it is efficiency rather than principle. Verifying the judgment dimensions is the audit: confirming a verdict means reading the same files the audit reads, so a submitted report saves the writing up and not the work. The independence argument survives too, since a repo grading itself produces a claim rather than evidence, but on its own it would have justified verifying a submission rather than declining one. A submitted report is also stale by construction. #508 was authored against hub 6501479 and merged at 839ecde, and two findings that postdated it had to be reconciled before it could be adopted. What downstream does instead is unchanged and is where its context is worth most: file findings about the hub as issues, which is the opposite of self-certification and has surfaced several real hub defects today, and apply fixes to its own repo per section 10. Also names the base branch, because #508 targeted main and I merged it without checking, which put content on main that develop lacked and needed a forward-port in #513. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the audit process documentation to explicitly assign audit report authorship to the hub repository and to state the correct base branch for hub-targeting PRs, closing the governance gap raised in #508.
Changes:
- Clarifies that audit reports under
reports/<repo>/audit.mdare authored by the hub (not submitted by the audited downstream repo). - Documents what downstream repos should do instead (file hub findings as issues; apply fixes via their own target PRs per section 10).
- States that any downstream PR opened against the hub must target
develop(notmain).
ptr727
added a commit
that referenced
this pull request
Aug 1, 2026
Records a decision that was carried only in conversation, at the maintainer's request. ## The gap `AUDIT.md` already states the **outcome**: the deterministic subset is "owner-initiated, run on demand when onboarding a repo, on suspected drift, or before fleet-wide changes." What it does not state is that **automation was explored and deliberately deferred**, or why. So the next person to notice that 13 of 21 repos have no committed report re-derives the whole analysis, and quite possibly reaches a different answer for reasons already rejected. ## What was considered, and what blocked it Three shapes: 1. A **scheduled hub-driven audit** publishing each report as a workflow artifact. 2. The same, **committing the report back**, the way the codegen bot updates its own files. 3. A **pull-request hook in each downstream repo**, auditing itself against the current hub. Three things blocked all three: - **Noise.** Until the fleet reaches stasis with every repo onboarded, a scheduled run reports mostly noise, because a repo mid-onboarding is *expected* to be non-conformant. Findings that are correct and not actionable train people to ignore the channel. - **Hub stability.** The hub has to be stable before downstreams can audit against it, since a hub change lands as fleet-wide findings the same day. Today is the worked example: `OPERATIONS.md` becoming universal in #507 created 17 findings, and declaring the merge-bot workflow in #512 created 6 more. - **A catch-22 on the downstream shape.** A self-auditing pull-request hook is CI instrumentation, and the repos that most need auditing are exactly the ones that do not carry it yet. The agreed outcome was the on-demand audit `AUDIT.md` describes today. ## Why the entry is actionable rather than a note It records the **preconditions** that would make reopening worthwhile (the fleet onboarded, and the hub going a stretch without carried-content changes) and **which shape to try first**: the artifact, because it produces evidence without committing anything, so it cannot generate review load while the noise level is still unknown. That makes the first experiment cheap and reversible. ## One correction to an existing entry The `reports/` entry read as a defect. It is not. Per the maintainer, the gap is **paced by capacity**, with repos brought up to spec as they are worked on, so the entry now says it records the outstanding set rather than a failure. This matters because #515 just put report authorship with the hub, and an entry that reads as an accusation invites re-opening a decision that was made deliberately. ## Verification ``` prose_lint TODO.md (dash, semicolon, charset, charset-unknown, dupword, spelling, sentence-split) clean markdownlint-cli2 (docker, canonical) 0 issues editorconfig-checker (docker, canonical) clean ``` Backlog only. The `[audit]` reference already pointed at `spec/audit.py`, so the new pointer to the document uses a separate `[audit-doc]` definition rather than overloading it. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
ptr727
added a commit
that referenced
this pull request
Aug 1, 2026
… the carried-file corrections to main (#517) Promotes twelve commits to `main`. Three of them change **carried** files, so downstream repos read the stale text until this lands, which is what makes the promotion the delivery step rather than bookkeeping. ## What this delivers to the fleet **Carried-file corrections**, picked up by every repo on its next re-vendor: | PR | File | Correction | | --- | --- | --- | | #514 | `.github/copilot-instructions.md` | Described the pre-split `AGENTS.md`, wrong in both halves. `GOVERNANCE.md` holds the rule sections and the two `intent` ones; `AGENTS.md` carries two verbatim sections and none repo-specific | | #514 | `CODESTYLE.md` | Said MD033 flags HTML elements while the config allows `details` and `summary`; also gains the `HISTORY.md` mirror rule, moved from a hub-only spec file so a repo can read the rule it is graded against | | #514 | `WORKFLOW.md` | D2.2 "skipped on smoke" read as the job rather than the validation, and a review acting on it proposed a change that would have coupled the release to smoke | | #503 | `.editorconfig`, `.gitattributes` | 36 comment findings in the files a new repo copies first | | #501 (earlier) | `repo-config/configure.sh` | Already on `main` | **Spec and requirement changes**: - **#507** makes `OPERATIONS.md` `appliesTo: "*"`, keyed to the need rather than to `workflowModel`. Measured: 3 of 21 repos carry it, so **17 will report a new `LETTER file:` finding**. Intended, and a headed stub satisfies it. - **#512** declares `.github/workflows/merge-bot-pull-request.yml` at `interface` fidelity, closing a graded contract (`WORKFLOW.md` D8.1) that no spec required. 15 of 21 already carry it, so this ratifies a de facto standard; the other **6 report a new `DRIFT`**, and those six have Dependabot pull requests piling up with nothing to merge them. - **#505** stops the audit flagging the hub against itself and drops a premise that was false since this repo went public. - **#511** fixes the README shape across repository visibility. - **#515** puts audit-report authorship with the hub and names the base branch, after a downstream conformance PR targeted `main` and I merged it without checking. - **#513** forward-ports that PR's content, restoring the forward-only invariant. **Backlog and reports**: #504, #506, #510, #516 record the README shape rework, the branch-bootstrap step, the declared-description design, and why the audit is on demand. ## Fleet consequence, stated before it lands Two owed follow-ups this promotion creates or carries: 1. **Re-vendor `repo-config/configure.sh`**, already owed from #501, since it is `verbatim` with `appliesTo: "*"` and every repo holding a copy is byte-mismatched. 2. **The next fleet audit reads noisier**, by 17 `OPERATIONS.md` letters and 6 merge-bot drifts. Both are new requirements rather than repo regressions. ## Verification Run on `develop` at `e4c76bc`: ``` python3 scripts/test_prose_lint.py 144 tests, OK python3 scripts/test_repo_gate.py 23 tests, OK python3 scripts/test_pr_review.py 27 tests, OK python3 spec/audit.py --selftest SELFTEST PASS python3 scripts/repo_gate.py eol 0, sha-pin 0 python3 spec/validate.py OK, 21 cataloged prose_lint --check charset --check dupword --check spelling clean editorconfig-checker (docker, canonical) clean ``` Every one of the twelve was merged green with a Copilot review covering its head SHA. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes the governance question #508 raised: may a downstream repo open a pull request against the hub to write its own audit report?
Why there was a vacuum
AUDIT.mdsaid the audit is read-only and produces a report underreports/, andAUDIT.mdsection 10 said "the hub audits and the agent applies the fixes via target PRs". Neither ever said who writes the report, so an agent filled the gap, reasonably.The answer: the hub authors it
The maintainer's call, and the argument that settles it is efficiency, not principle:
That is correct and it dismantles the case I had been making. I argued a submitted report preserves downstream context the hub would otherwise rebuild. But verifying the judgment dimensions is the audit: confirming a verdict like "analyzers enforced,
TreatWarningsAsErrorspresent" means reading the same files the audit reads. Only the deterministic subset is cheap. So a submitted report saves the writing up, which is the trivial part once the audit is done.The independence argument survives as a second reason, since a repo grading itself produces a claim rather than evidence, but on its own it would only have justified verifying a submission rather than declining one.
A third reason #508 demonstrated
A submitted report is stale by construction. It is a snapshot of one hub revision arriving at a later one. #508 was authored against hub
6501479and merged at839ecde, and before adopting it I had to reconcile two findings that did not exist when it was written:OPERATIONS.mdbecame universal in #507, and the merge-bot workflow was declared in #512. That reconciliation is inherent to the workflow, not incidental.What downstream still does, and it matters
Unchanged, and it is where downstream context is worth most:
WORKFLOW.mdD8.1 graded it,copilot-instructions.mddescribing a pre-splitAGENTS.md,CODESTYLE.mdcontradicting the markdownlint config, and D2.2 wording that nearly caused a real regression.Also names the base branch
#508targetedmain, and I merged it without checkingbaseRefName. That put content onmainthatdeveloplacked, breaking the forward-only invariant, and needed a forward-port in #513.The branching model was already stated in
GOVERNANCE.md, but not in the place an agent opening a conformance pull request against the hub would be reading. It is now stated here too.Verification
Prose only, no engine change.
AUDIT.mdis carried atintent, so downstream repos pick this up on their next re-vendor.What this does not solve
Thirteen of twenty-one cataloged repos still have no committed audit report, tracked in
TODO.md. This decision means the hub writes them, which is a capacity question rather than a governance one. Accepting unverified submissions would have closed the gap by lowering the bar rather than by doing the audits.🤖 Generated with Claude Code