Spec questions from the PhotoCleaner conformance sweep (3 hub-side defects)

[ptr727]

Five spec questions surfaced by the PhotoCleaner conformance sweep of 2026-08-01, raised per AUDIT.md section 9 rather than resolved downstream. Three are hub-side defects that re-vendor fleet-wide, so each wants its own change.

Run stamp: audit run 2026-08-01T15:30:19Z | hub 6501479. The report is refreshed in #508, and PhotoCleaner PRs #26-#31 merged the convergence.

1. .github/copilot-instructions.md still describes the pre-split AGENTS.md

The carried Reviewing Carried Fleet Content section 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, is byte-locked ...

After the router split that is wrong in both halves. The rule sections live in GOVERNANCE.md, and it is GOVERNANCE.md that holds the two intent sections (Devcontainer, Repository Layout); AGENTS.md carries exactly two verbatim sections and no repo-specific ones.

This is carried at intent, so PhotoCleaner adapted the wording on the way down. Every other repo that carries the section inherits the stale description, and a reviewer following it looks for byte-locked rule text in the wrong file.

2. CODESTYLE.md contradicts .markdownlint-cli2.jsonc on MD033

CODESTYLE.md "Markdown and Spelling" item 1 says:

MD033 inline HTML stays enabled: HTML comments are permitted (markdownlint does not flag them), HTML elements are flagged, and anything with a native markdown equivalent uses the markdown.

The canonical config now sets "MD033": { "allowed_elements": ["details", "summary"] }, so two elements are not flagged. The prose was not swept when the config changed, which is the GOVERNANCE.md rule "when you change a behavior, search for prose that asserts the old one" applied to the hub's own files.

3. spec/readme-structure.md has no behavior for a private repository

shields.io cannot read a private repo, so every GitHub-sourced badge in Build Status and Releases renders broken. The spec states no behavior for that case, and section 2 reads as unconditional.

This is not a corner case: a repo is often private precisely while it is being made presentable, which is exactly when its README is written. PhotoCleaner is private now and goes public later, so its README carries Docker Hub shields only and picks up the GitHub ones at the visibility flip. Worth a sentence in the spec saying whether the GitHub-sourced shields are deferred or written-and-broken, so each repo does not decide separately.

4. The HISTORY.md mirror rule has no carried home

spec/readme-structure.md owns it and spec/audit.py enforces it, but that file is hub-only, so a downstream repo cannot point at the rule it is measured against. PhotoCleaner kept it as repo-local prose in CODESTYLE.md for want of a destination, which is duplication the fleet normally avoids.

Either promote it into a carried section, or state plainly that mechanical-only enforcement is the intent so downstream stops inventing a local copy.

5. WORKFLOW.md D2.2 "skipped on smoke" is ambiguous

D2.2 says the gate "is skipped on smoke". That names the validation, and scenario S1 confirms it: validate-release **skipped (smoke), succeeds**.

A Copilot review on PhotoCleaner#29 read it as the GitHub job status and proposed a job-level if: !inputs.smoke. That would have been a real regression: github-release has validate-release in its needs, and a skipped need skips the dependent, so the release job would have been coupled to smoke through a second path on top of the if: it already carries.

The canonical is right; the wording invites the misreading. Something like "the check exits early on smoke, and the job still reports success" would close it.

Not a spec question

A sixth item was raised with the PhotoCleaner maintainer and is answered: the repo is private deliberately and temporarily, going public once the conformance work settles, so the declared github-release channel becomes satisfiable at that flip rather than being wrong now. Recorded in the registry driftNotes in #508.

[ptr727]

On PhotoCleaner#32: hold the parser, the source of truth is moving

The maintainer has decided the direction, and it changes the answer for #32 rather than only refining it. Raising it here because #32 is merged and the other Docker repos would copy it next.

What #32 does, and why the care in it is the diagnosis

The step reads the intro line after the README H1 at publish time and pushes it as the Docker Hub short description. It handles CRLF, and rejects headings, block quotes, all four unordered list markers, ordered lists by regex, HTML, tables, code spans, links, images, and the 100-character cap. Nine guards, each with a comment explaining the failure it prevents.

That is careful work and the reasoning in it is sound. It is also the measurement of the approach: nine guards is what extracting a semantic value out of prose costs.

The objection is the failure mode, not the parsing

Every guard ends in exit 1, inside a job gated on push && branch == main. So a restructured README fails the release, over a tagline. Failing loud is right for a gate. Here it converts cosmetic drift into a blocked publish, which is a worse outcome than the drift.

There is also a split it creates. The README intro feeds three surfaces: the README, the GitHub About panel, and the Docker Hub short description. repo-config/configure.sh does not manage description at all, so GitHub About is audit-only. After #32 one mirror self-heals and two do not, while the audit checks all three.

One counter-argument deserves stating, because it is why #32 looked locally right: Docker Hub's long description is already CI-pushed from Docker/README.md. The difference is that pushing Docker/README.md ships a file written for that purpose, verbatim, and cannot misparse. The short description derives a sentence from a different file.

The direction: declare it, do not derive it

The parsing exists only because the canonical value lives inside prose. So the value moves into registry/repos.json as a description field, and the README intro becomes a third mirror rather than the source:

• the audit compares README intro, GitHub About, and Docker Hub short all against one declared string, with no extraction anywhere
• the Docker workflow pushes a literal, so no parser, no nine guards, and no release-blocking failure over a tagline
• configure.sh can set the GitHub About panel from the same field it already uses for every other repository setting, making all three mirrors managed the same way
• the 100-character cap stays, since Docker Hub is still the tightest surface it feeds

Recorded in the hub's TODO.md in #510. The field is mechanical, and populating it needs a per-repo decision wherever the current intro exceeds the cap, which is PhotoCleaner's case today at 150 characters.

What this means for PhotoCleaner

No revert needed, and no urgency. #32 works and the guards make it safe. The ask is only to not propagate the step to the other Docker repos, because it becomes redundant once the field lands and the same nine guards would be copied four more times. When the field ships, the step collapses to passing short-description from the registry value.

For the record, the audit independently confirms the finding that motivated #32: this hub's own live audit of PhotoCleaner reports the 150-character intro over the cap, and both mirror divergences, the GitHub About panel and the Docker Hub short description. The problem #32 set out to fix is real. Only its mechanism changes.

[ptr727]

Closed: all five items verified fixed

Re-checked line by line against develop at 1ed0cc8 rather than against the tree as it stood when this was filed.

Item	Evidence
1. copilot-instructions.md describes the pre-split AGENTS.md	e4c76bc (#514)
2. CODESTYLE.md contradicts .markdownlint-cli2.jsonc on MD033	e4c76bc (#514)
3. readme-structure.md has no behavior for a private repository	4ee9bbe (#511)
4. The HISTORY.md mirror rule has no carried home	e4c76bc (#514)
5. WORKFLOW.md D2.2 "skipped on smoke" is ambiguous	e4c76bc (#514)

Both commits are on main.

Item 1. .github/copilot-instructions.md now reads "Most of GOVERNANCE.md is universal fleet law" and describes AGENTS.md as the thin router carrying two byte-locked sections of its own and no repository-specific ones. Both halves of the stale description are corrected.

Item 2. CODESTYLE.md "Markdown and Spelling" now reads "details and summary are allowed because a GitHub collapsible has no markdown equivalent, every other element is flagged", matching the config's "MD033": { "allowed_elements": ["details", "summary"] }.

Item 3. Answered as written-and-broken rather than deferred, which is the opposite of the shape PhotoCleaner had adopted. spec/readme-structure.md now states it outright: a private repo carries the same sections and the same shield set as a public one, its GitHub-sourced badges render broken until it goes public, and that is accepted rather than worked around. The reasoning given is that the alternative makes the README shape depend on a property that is temporary by design, so going public becomes a visibility change and nothing else.

Item 4. spec/readme-structure.md now says the rule lives in CODESTYLE.md "Markdown and Spelling", which every repo carries, so a repo can read the rule it is measured against, and this file states only what the audit does with it. The downstream duplication this item flagged no longer has a reason to exist.

Item 5. D2.2 now reads "on a smoke build the check exits early while the job still reports success", and goes further than the suggested wording by spelling out the failure the misreading would cause, that a job-level if: skips the job, a dependent skips with it unless it opts out with if: always(), and github-release carries validate-release in needs: without opting out.

Not dropped by this close. The separate disposition in the comment above, moving the canonical short description into registry/repos.json instead of parsing it out of the README, is not part of these five items and is tracked in the hub TODO.md under "Audit and Spec Model".