Record why the audit is on demand, and what would reopen it - #516
Merged
Conversation
AUDIT.md already says the audit is owner-initiated and run on demand. What it does not say is that automation was explored and deliberately deferred, or why, so the reasoning was carried only in conversation and would be re-derived from scratch by whoever asks next. Three shapes were considered: a scheduled hub-driven audit publishing each report as a workflow artifact, the same thing committing the report back the way the codegen bot updates its own files, and a pull-request hook in each downstream repo auditing itself against the current hub. Three things blocked all three. A scheduled run reports mostly noise until every repo is onboarded, since a repo mid-onboarding is expected to be non-conformant. The hub has to be stable first, because a hub change lands as fleet-wide findings the same day. And the downstream half is a catch-22, since a self-auditing hook is CI instrumentation the repos that most need it do not carry. Also records the preconditions that would make it worth reopening and which shape to try first, so the entry is actionable rather than a note that it was once discussed. The reports/ entry now says the gap is paced by maintainer capacity rather than blocked, since repos are brought up to spec as they are worked on. It was reading as a defect and it is not one. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
🟢 Ready to approve
The change is limited to well-formed markdown/prose updates in TODO.md with no functional or behavioral impact.
This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.
Pull request overview
This PR updates TODO.md to capture previously conversational context about why the fleet audit remains on-demand, what automation approaches were considered, what blocked them, and what conditions would justify reopening automation later.
Changes:
- Reframes the “populate reports/” backlog item as capacity-paced tracking rather than a defect.
- Adds a new backlog entry summarizing the explored-but-deferred audit automation options and the specific blockers.
- Adds a new link reference (
[audit-doc]) pointing toAUDIT.mdwithout overloading the existing[audit]reference.
File summaries
| File | Description |
|---|---|
| TODO.md | Expands backlog entries to record audit-automation decision rationale and adds a dedicated link reference to AUDIT.md. |
Review details
- Files reviewed: 1/1 changed files
- Comments generated: 0
- Review effort level: Lite
We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.
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.
Records a decision that was carried only in conversation, at the maintainer's request.
The gap
AUDIT.mdalready 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:
Three things blocked all three:
OPERATIONS.mdbecoming universal in Key OPERATIONS.md to the need for it, not to the workflow model #507 created 17 findings, and declaring the merge-bot workflow in Declare the merge-bot workflow the release contract already grades #512 created 6 more.The agreed outcome was the on-demand audit
AUDIT.mddescribes 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
Backlog only. The
[audit]reference already pointed atspec/audit.py, so the new pointer to the document uses a separate[audit-doc]definition rather than overloading it.🤖 Generated with Claude Code