Conversation
Adds one backlog item to the README TODO section: refresh the stale README and evaluate a lower-maintenance structure (a per-section index pointing into the docs with short descriptions, keeping the README as the adoption + audit-instruction entry point), noting the sync obligation such a structure carries. Docs-only. `spec/validate.py` OK. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Adds one backlog item: a linter-only Python project type for codegen/boilerplate Python (no tests, no coverage, linter only) distinct from the existing `python` type for utility code (tests + coverage). Records that ESPHome-Config's `+python` reclassification is deferred until the type exists, and its one outstanding finding is accepted meanwhile. Docs-only. `spec/validate.py` OK. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
## What
The `audit.py` branch-drift check split by direction: a path develop
still holds at the merge-base is a genuine forward-sync ("develop
lacks"); a path both branches moved off the base is `diverged` and
reported as "changed on both main and develop … develop may already
supersede main."
## Why
Surfaced by the PlexCleaner convergence (ptr727/PlexCleaner#880): the
check flagged 4 workflow files as "develop lacks (forward-sync needed)"
when develop was actually **ahead** (it carried the release-task
re-vendor #882 that main lacked). The old logic only tested `main !=
develop` among main-side changes, never whether develop was behind or
ahead, so a both-changed file read as a develop deficit. Forward-syncing
per that framing would have reverted develop's work.
## Verification
- `python3 spec/audit.py --selftest` PASS; `spec/validate.py` OK.
- Live: PlexCleaner's 4 workflow files now report as `diverged`
(accurate) instead of `develop lacks`.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>## What Replaces the force-success tail on the artifact-delete in `build-release-task.yml`'s `github-release` cleanup step with the `if ! …; then` form. ## Why Routed upstream from the PlexCleaner convergence (ptr727/PlexCleaner#880): Copilot flagged a force-success tail on a mutation, which the write-safety rule bans. The listing step two lines above already uses the compliant `if ! ids=$(…); then` form, so the delete was internally inconsistent. The new form reads the delete's result via the `if`, surfaces a failed delete as a visible `::warning::`, and the `retention-days: 1` backstop still reaps the artifact - functionally identical, rule-compliant. Changes the `github-release` verbatim region, so it re-vendors fleet-wide next cycle. ## Verification YAML valid, `spec/audit.py --selftest` PASS, `spec/validate.py` OK. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Promotes the doc/spec-only work from develop to main, including a refinement to the audit branch-drift check and a small workflow-snippet cleanup to align with the repo’s write-safety guidance.
Changes:
- Add
classify_branch_drift()to split main-side branch drift intobehindvsdiverged, and extendspec/audit.py --selftestto cover it. - Add two README backlog items (README refresh + new “linter-only Python” project type concept).
- Update the canonical
build-release-task.ymlsnippet to avoid a force-success tail on the artifact-delete call.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| spec/audit.py | Adds branch-drift direction classification plus selftest coverage, and updates drift reporting to distinguish behind vs diverged. |
| README.md | Adds backlog TODO items documenting future work around README structure and a linter-only Python type. |
| catalog/snippets/workflows/build-release-task.yml | Rewrites artifact deletion to use an if ! ...; then form instead of a force-success tail. |
Uh oh!
There was an error while loading. Please reload this page.
Reword the `behind` branch-drift DRIFT message from "develop lacks <path>" to "develop is behind on". Routed from Copilot on the promotion #434: the `behind` bucket also catches a path main deleted that develop still carries, where "develop lacks" misreads (develop *has* the path; main removed it). "develop is behind on" is accurate for additions, modifications, and deletions alike. `spec/audit.py --selftest` PASS, `spec/validate.py` OK. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Uh oh!
There was an error while loading. Please reload this page.
The degraded branch-check fallback (three-tree filter cannot run - a tree is truncated or unavailable) has only the compare's file count, which cannot tell direction or filter cherry-picked content-equivalent changes. Reword it to assert only what is known - the paths differ, and a forward-sync or reconciliation may be needed - instead of claiming develop is behind. Routed from Copilot on promotion #434. `spec/audit.py --selftest` PASS, `spec/validate.py` OK. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Uh oh!
There was an error while loading. Please reload this page.
This was referenced Aug 22, 2026
Merged
Merged
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 freeto 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.
Promote develop to main
Four doc/spec-only changes, all squashed to develop and Copilot-clean:
pythontype; ESPHome-Config+pythondeferred until it exists.audit.pybranch check now splits "develop genuinely behind" (forward-sync) from "changed on both / develop may supersede", with aclassify_branch_drift()helper + selftest. Surfaced by the PlexCleaner convergence, where develop was ahead but read as a forward-sync gap.build-release-task.ymlartifact-delete uses theif ! …; thenform instead of a force-success tail (matches the listing step; write-safety compliant). Changes thegithub-releaseverbatim region → fleet re-vendors next cycle.No code/workflow changes to the hub's own pipeline - documentation and spec only, so no release fires on merge.
Verification
spec/validate.pyOK;spec/audit.py --selftestPASS.🤖 Generated with Claude Code