From e3d6c775957212e9c9ce05e019e3d45b25d98848 Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Sat, 1 Aug 2026 11:40:20 -0700 Subject: [PATCH] Put report authorship with the hub, and name the base branch #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) --- AUDIT.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/AUDIT.md b/AUDIT.md index bac5e335..7f2e0551 100644 --- a/AUDIT.md +++ b/AUDIT.md @@ -117,6 +117,10 @@ A repo is **operational** only if every applicable check passes. A single applic Write `reports//audit.md` from [`reports/_template.md`][template]: a dimension x {letter, intent, verdict, evidence} table with `file:line` citations (WORKFLOW.md 5A style), a drift section, and a list of proposed registry/spec updates (e.g. a resolved `classificationPending`). Rank findings most severe first. +**The hub authors the report, and a downstream repo does not open a pull request against the hub to write its own.** `reports/` is the hub's evidence that it audited a repo, so a report written by the repo being audited is a claim rather than evidence, and the hub cannot adopt one without checking it. Checking the judgment dimensions **is** the audit, since confirming a verdict like "analyzers enforced" means reading the same files the audit reads, so a submitted report saves only the writing up and not the work. A submitted report is also stale by construction, because it is a snapshot of one hub revision arriving at a later one, and its claims then have to be reconciled against findings that did not exist when it was written. + +What a downstream repo does instead is unchanged and is where its context is worth most: it **files findings about the hub as issues**, which is the opposite of self-certification and is how several hub defects have been found, and it **applies fixes to its own repo** per section 10. Any pull request it does open against the hub follows the same branching model as every other, targeting `develop` and never `main`. + **Findings are a point-in-time snapshot. Stamp them and re-verify before acting.** [`spec/audit.py`][audit-runner] prints a run stamp (`audit run | hub `) and, per repo, the exact commit it read (`@ @`). Anything derived from a run (a report, and especially an **onboarding or conformance issue**) quotes that stamp, so a reader can tell whether it still applies. A convergence issue is generated from the audit, never composed by hand: `spec/audit.py --issue ` emits a ready-to-file title and body from that repo's live findings (grouped into must-fix, converge, and could-not-verify), so the issue content cannot drift from what the audit actually found and regenerates as the repo changes. **Verify a convergence before it is promoted with `--branch`.** `spec/audit.py --branch ` reads that ref instead of the repo's registry `groundTruthBranch`, so a repo can audit its own `develop` while the work is still in flight rather than discovering the gaps after `main` has moved. The registry is not edited, the run is still read-only, and the run stamp names the override so a finding cannot be mistaken for one against ground truth. A ref that does not resolve is a single error naming it, never a baseline's worth of file-absent letters.