Forward-port the PhotoCleaner audit refresh to develop - #513
Merged
Conversation
The committed `reports/photocleaner/audit.md` was dated 2026-07-23 and predated the release pipeline, so it still listed both branch rulesets as missing and the Dockerfile as dead weight. All of that landed, and release `1.0.9` shipped that same day. Re-audited against `main@15b9b5b`. **Run stamp:** `audit run 2026-08-01T15:30:19Z | hub 6501479` ## What the re-audit found Everything the old snapshot called a defect is fixed. The remaining findings are a different set, created mostly by **this hub advancing** rather than by the repo regressing: | | | | --- | --- | | **defect** | The agent instruction set predates the router split: `GOVERNANCE.md` absent, `AGENTS.md` still the pre-split single file, so neither verbatim region compares and all ten sections read as undeclared | | **defect** | README intro 150 chars against the 100-char cap, with the Docker Hub short description no longer mirroring it | | **drift** | `.markdownlint-cli2.jsonc` and `repo-config/configure.sh` both match a past hub revision | | **drift** | `build-release-task.yml` has no `validate-release` job, though that repo's own `WORKFLOW.md` names it in D2.2 and in scenarios S1, S4, and S10, and its `github-release` body matches no hub revision | `develop` and `main` report identical findings, so the commit-count gap remains the benign promotion-merge ancestry artifact. ## Convergence Six PRs are open against PhotoCleaner `develop`, one per drift class per AUDIT.md section 10, each with a Copilot review on its head SHA, left for the maintainer to merge. They are listed in the report. ## Three hub-side defects this surfaced Raised per AUDIT.md section 9 rather than resolved here, since each re-vendors fleet-wide and deserves its own change: 1. **The hub's own `.github/copilot-instructions.md` describes the pre-split file.** `Reviewing Carried Fleet Content` says "Most of `AGENTS.md` is universal fleet law: every section that states a rule, as opposed to the two that describe this repository's own directory tree and devcontainer". After the split those sections are in `GOVERNANCE.md`, and `AGENTS.md` carries exactly two verbatim sections and no repo-specific ones. PhotoCleaner had to adapt the text on the way down, and every other repo carrying it inherits the stale description. 2. **`CODESTYLE.md` contradicts `.markdownlint-cli2.jsonc` on MD033.** The prose still says "HTML elements are flagged" after the config gained `allowed_elements: ["details", "summary"]`. This is the "when you change a behavior, search for prose that asserts the old one" rule, unswept. 3. **`spec/readme-structure.md` assumes a public repository.** PhotoCleaner is private, so shields.io cannot read its GitHub release, build, or commit data and every GitHub-sourced badge renders broken. Build Status and Releases state no behavior for that case. Plus two softer ones: the `HISTORY.md` mirror rule lives only in hub-only `spec/readme-structure.md`, so a downstream repo cannot point at the rule it is measured against; and `WORKFLOW.md` D2.2's "skipped on smoke" is ambiguous enough that a Copilot review read it as the GitHub job status and proposed a change that would have coupled `github-release` to smoke through its `needs`. ## driftNotes Dropped the stale claim that the report predates the release wiring, dropped the cross-repo comparison (the "Carried files carry no coordination references" rule bans a sibling repo named as an illustrative example, and a registry entry is the same shape of problem), and recorded that the repo is private while its Docker image is public, so the declared `github-release` channel is not pullable by a consumer. ## Verification - `spec/validate.py`: "Spec validation OK: 21 cataloged, 0 backlog repos classify cleanly." - `scripts/repo_gate.py`: eol 0 issues, sha-pin 0 issues. - `scripts/prose_lint.py` on the report: exit 0. - `markdownlint-cli2` on the report: 0 issues. --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Forward-ports the PhotoCleaner audit refresh from main onto develop to restore the forward-only branch invariant and prevent future promotion conflicts/reverts. The changes update the audit snapshot and align the registry’s PhotoCleaner notes with the refreshed report.
Changes:
- Refresh
reports/photocleaner/audit.mdwith the 2026-08-01 re-audit snapshot, updated dimension verdicts, drift findings, and escalations. - Update the PhotoCleaner entry in
registry/repos.jsonto refresh/expanddriftNotesto match the new audit state (including current visibility constraints).
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| reports/photocleaner/audit.md | Updates the PhotoCleaner audit snapshot (date/run stamp), findings, and escalations to reflect the latest re-audit. |
| registry/repos.json | Refreshes PhotoCleaner driftNotes to match the updated audit conclusions and current repo visibility implications. |
ptr727
added a commit
that referenced
this pull request
Aug 1, 2026
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.md` said the audit is read-only and produces a report under `reports/`, and `AUDIT.md` section 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**: > consider you want it in develop, and you want to audit it anyway, you are going to run the same effort, and the result would be the same if you agree with their audit 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, `TreatWarningsAsErrors` present" 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 `6501479` and merged at `839ecde`, and before adopting it I had to reconcile two findings that did not exist when it was written: `OPERATIONS.md` became 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: - **File findings about the hub as issues.** The opposite of self-certification, and it has surfaced several real hub defects today: the merge-bot workflow that no spec required while `WORKFLOW.md` D8.1 graded it, `copilot-instructions.md` describing a pre-split `AGENTS.md`, `CODESTYLE.md` contradicting the markdownlint config, and D2.2 wording that nearly caused a real regression. - **Apply fixes to its own repo** per section 10. ## Also names the base branch `#508` targeted **`main`**, and I merged it without checking `baseRefName`. That put content on `main` that `develop` lacked, 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_lint AUDIT.md --check charset --check dupword --check spelling --check charset-unknown clean markdownlint-cli2 (docker, canonical) 0 issues editorconfig-checker (docker, canonical) clean python3 spec/validate.py OK, 21 cataloged ``` Prose only, no engine change. `AUDIT.md` is carried at `intent`, 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](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.
Restores the forward-only invariant after I merged #508 without checking its base branch.
What happened
#508 was opened against
main, notdevelop. I verified its content, its checks, and its review threads, and merged it without ever readingbaseRefName. It landed as048a442onmainalone.The branching model is feature to
developby squash, thendeveloptomainby promotion merge. A feature PR merged straight tomainputs content onmainthatdevelopdoes not have, which is exactly the divergence the forward-only rule exists to prevent. Left alone, the next promotion either conflicts or silently reverts the audit refresh, sincedevelopwould carry the olderreports/photocleaner/audit.md.The fix
048a442cherry-picked ontodevelop. Confirmed it is the only content commitmainholds thatdeveloplacks:Everything below
048a442is a promotion merge commit, main-only by construction, which is topology rather than drift. After this merges, the two branches carry identical content again and the next promotion is clean.Two separate errors, worth naming
Mine: I ran the full merge gate, checks, review coverage, unresolved threads, and an independent re-audit of the report's claims, and never checked which branch the PR targeted. A base-branch check belongs in that gate, and it was not in it.
The PR's: a downstream conformance PR against the hub targeted
main. That is the same class as the report-authorship question #508 raised, an agent filling a gap the instructions never addressed, and it argues forAUDIT.mdstating the base branch explicitly alongside who may author a report.Verification
Content-identical to
048a442, so no review of the report's substance is re-opened here. It was verified against a livespec/audit.py PhotoCleanerrun before #508 merged, and every substantive claim was corroborated.🤖 Generated with Claude Code