From 0534b30f3600754810c6b81f39bff1b20aebe00d Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Sun, 5 Jul 2026 07:42:14 -0700 Subject: [PATCH 1/2] Add the Converge step to the audit procedure Document the convergence model: the audit is read-only, but its drift is resolved by the agent applying fixes via a pull request on the target repo, driving the Copilot review to green, and holding the merge for the maintainer - one focused PR per drift class, with systemic drift fixed in the hub. Supersedes the hub-only-reports framing. Co-Authored-By: Claude Opus 4.8 (1M context) Signed-off-by: Pieter Viljoen --- AUDIT.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/AUDIT.md b/AUDIT.md index e3500fe7..9dfa9d5c 100644 --- a/AUDIT.md +++ b/AUDIT.md @@ -80,6 +80,18 @@ Write `reports//audit.md` from [`reports/_template.md`][template]: a dimen Surface spec questions rather than resolving them silently - e.g. the Python config-placement canonicalization, or a new construct no type covers. A repeated letter miss that many repos share is a signal the spec (not each repo) needs adjusting; raise it. +## 10. Converge - Apply the Fixes + +The audit is read-only, but the drift it finds is **resolved by applying fixes to the target repo, not left as a report**. The convergence loop: + +- **Apply via a pull request on the target repo.** Branch from the target's `develop` (or `main` for a `main`-only repo), make the fix, and open a PR. Never push a fix directly to a protected branch, and never hand-edit a target outside a PR. +- **Drive the PR's Copilot review to green** - the same loop this repo runs (see [AGENTS.md "PR Review Etiquette"][agents] and the Copilot runbook): request review on every push, address and resolve every thread, and confirm the review covers the head SHA. +- **Merge only with explicit maintainer approval.** The agent drives to green and stops; the maintainer merges. +- **One focused PR per drift class**, cross-referencing the audit finding - a sprawling all-drifts PR draws many review rounds and never feels done. +- **Fix systemic drift in the hub, not per repo.** When many repos share a drift, fix the spec/rule (or add a machine check) here and let a re-audit re-flag it, rather than hand-patching each repo for the shared cause. + +The convergence model: the hub audits and the agent **applies** the fixes via target PRs, and the maintainer gates every merge. It supersedes any "the hub only reports; downstream operators apply by hand" framing. + [workflows]: ./catalog/snippets/workflows/ From 3576e3305a56127de56539ae455d52c36af8da7a Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Sun, 5 Jul 2026 07:45:24 -0700 Subject: [PATCH 2/2] Clarify the read-only audit phase and name the Copilot runbook file Distinguish the read-only audit-and-report phase (sections 1-9) from the separate Converge phase that applies fixes, and point the Copilot review runbook reference at .github/copilot-instructions.md. Co-Authored-By: Claude Opus 4.8 (1M context) Signed-off-by: Pieter Viljoen --- AUDIT.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/AUDIT.md b/AUDIT.md index 9dfa9d5c..cebd4be8 100644 --- a/AUDIT.md +++ b/AUDIT.md @@ -82,10 +82,10 @@ Surface spec questions rather than resolving them silently - e.g. the Python con ## 10. Converge - Apply the Fixes -The audit is read-only, but the drift it finds is **resolved by applying fixes to the target repo, not left as a report**. The convergence loop: +Sections 1-9 (the audit and its report) are **read-only** - they never touch the target. **Converging** is the separate follow-on phase: the drift the report found is **resolved by applying fixes to the target repo**, not left as a report. The convergence loop: - **Apply via a pull request on the target repo.** Branch from the target's `develop` (or `main` for a `main`-only repo), make the fix, and open a PR. Never push a fix directly to a protected branch, and never hand-edit a target outside a PR. -- **Drive the PR's Copilot review to green** - the same loop this repo runs (see [AGENTS.md "PR Review Etiquette"][agents] and the Copilot runbook): request review on every push, address and resolve every thread, and confirm the review covers the head SHA. +- **Drive the PR's Copilot review to green** - the same loop this repo runs (see [AGENTS.md "PR Review Etiquette"][agents] and the [Copilot review runbook][copilot-runbook] in `.github/copilot-instructions.md`): request review on every push, address and resolve every thread, and confirm the review covers the head SHA. - **Merge only with explicit maintainer approval.** The agent drives to green and stops; the maintainer merges. - **One focused PR per drift class**, cross-referencing the audit finding - a sprawling all-drifts PR draws many review rounds and never feels done. - **Fix systemic drift in the hub, not per repo.** When many repos share a drift, fix the spec/rule (or add a machine check) here and let a re-audit re-flag it, rather than hand-patching each repo for the shared cause. @@ -100,6 +100,7 @@ The convergence model: the hub audits and the agent **applies** the fixes via ta [agents]: ./AGENTS.md [codestyle]: ./CODESTYLE.md +[copilot-runbook]: ./.github/copilot-instructions.md [project-types]: ./spec/project-types.json [readme-structure]: ./spec/readme-structure.md [repo-config]: ./repo-config/