Genericize verbatim sections for clean carry; mask needs; section advisories - #422
Merged
Conversation
…isories The verbatim sweep (#420) exposed that the canonical AGENTS sections carried hub-local content that breaks when byte-carried to the fleet, surfaced by the PlexCleaner convergence. - De-link 31 hub-only relative links (registry/catalog/spec/reports/STANDUP/ operational) - 24 inside verbatim sections (they 404 downstream and violate the carried-files rule that now sits verbatim in the same file); the preamble and the two intent sections keep their valid hub-navigation links. - Mask a job's owned needs: list in normalize() (like the action pin), so a correctly-subsetted github-release byte-matches - an unvendored needs name fails the workflow to load, so pruning is mandatory. Selftest covers it. - Operational Repositories -> appliesTo * so the 3 cross-references to it from Foundational Principles, Branching Model, and Release Model resolve everywhere. - Reclassify Repository Onboarding and Conformance as hub-only (drop from the carried manifest): it is hub-audit machinery (registry reconciliation, STANDUP cold-start, conformance matrix) a downstream agent never runs, and its one universal rule lives in AUDIT.md. It stays in the hub AGENTS.md as context. - section-model.md: reconcile a content-duplicate section (heading differs, content duplicates a verbatim section) by content not heading; audit.py now lists a repo's undeclared H2 sections as an advisory so the reconciliation is not missed. A repo may still carry its own project-specific sections. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the spec/audit carry model so verbatim-carried AGENTS.md sections and workflow job regions remain byte-comparable across repos while removing hub-only navigation/linkage that breaks downstream byte-carry.
Changes:
- Updates the AGENTS.md section model and baseline to carry
Operational Repositoriesverbatim for all repos, and treatsRepository Onboarding and Conformanceas hub-only (not part of the carried baseline). - Extends verbatim normalization in
spec/audit.pyto mask workflow jobneeds:(in addition to action pins and EOL), and adds selftest coverage for the new behavior. - Adds an advisory drift finding when a repo’s AGENTS.md contains undeclared H2 sections, to surface reconciliation needs without failing the audit.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| spec/section-model.md | Updates section classification notes (including hub-only vs carried) and documents the new undeclared-section advisory behavior. |
| spec/files.json | Adjusts the AGENTS.md carried-section baseline: carries Operational Repositories for all; removes Repository Onboarding and Conformance from the carried manifest. |
| spec/fidelity-model.md | Documents the expanded verbatim normalization scope (now includes workflow job needs:). |
| spec/audit.py | Implements needs: masking during normalization, adds undeclared-section advisory logic, and adds selftest coverage. |
| AGENTS.md | Removes/avoids hub-only links in verbatim-carried sections so the content can be carried byte-clean downstream. |
…, path, lead phrase - normalize() masks the block-list and scalar needs: forms too, not just inline (with a guard test that masking a block list does not eat the next key). - Drop the Repository-Onboarding special-case from the undeclared-section advisory, so a repo still carrying that hub-only section is flagged to remove it. - AGENTS.md: use the full repo-relative path repo-config/operational/develop.json. - fidelity-model.md: the Normalization lead phrase now names all three dimensions. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
[^\]]* matched newlines, so an unclosed inline list could swallow across lines to a distant ]. Use [^\]\n]* so the inline branch stays on one line; the block branch already handles a genuine multi-line list. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The hub's own AGENTS.md legitimately carries hub-only sections (Repository Onboarding and Conformance), so auditing ProjectTemplate against itself would false-positive on them. Skip the advisory when the repo is the hub; a downstream repo carrying such a section is still flagged. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
ptr727
added a commit
that referenced
this pull request
Jul 24, 2026
…cription rule (#422, #423) (#424) Two governance PRs refining the section-fidelity model from downstream feedback: - **#422** - genericize the verbatim AGENTS sections for clean carry (de-link 24 hub-only 404 links), mask a job's owned `needs:` list in normalize(), Operational Repositories appliesTo:*, reclassify Repository Onboarding as hub-only, and add the content-duplication reconciliation rule + an undeclared-section audit advisory (hub exempted). Resolves the hub-side issues the PlexCleaner convergence surfaced. - **#423** - one canonical <=100-char description across README / GitHub About / Docker Hub, with H1-name and length audit checks. **Fleet impact:** re-vendors the (now clean) verbatim AGENTS sections and the Repository Details section; the audit gains the section advisory + the description checks. Burned down via the AGENTS refreshes already in motion. Merge commit, no release fires.
This was referenced Jul 24, 2026
ptr727
added a commit
that referenced
this pull request
Jul 24, 2026
## What Removes three hub-only `catalog/…` references still sitting as prose inside **verbatim** AGENTS.md sections after the #422 genericization. ## Why The "carried files carry no coordination references" rule (Documentation Style / carried-files) bans a reference inside byte-locked fleet text to a path a given repo does not carry. A downstream repo carries none of `catalog/`, so each of these was both a rule violation and a guaranteed Copilot false positive on every AGENTS.md re-vendor - the same friction PlexCleaner#880 flagged. This finishes what #422 started. ## Changes - **Branching Model:** `catalog/snippets/workflows/run-codegen-pull-request-task.yml` -> "the codegen workflow" (behavioral; the codegen workflow has no carried `.github/…` path since it is catalog-only, unlike the dependabot/merge-bot workflows named alongside it). - **Documentation Style Conventions (Line Endings):** dropped the `(and the catalog snippet workflows in catalog/snippets/workflows/*, pinned LF the same way)` aside. Redundant - `.editorconfig` enforces the LF pin and its own comment carries the rationale. - **Editor and Tasks:** dropped the trailing `The catalog holds the full set and per-language additions: catalog/snippets/vscode/.` The standard set and per-language additions are already enumerated inline in the same bullet. **Kept:** the load-bearing cross-model `repo-config/operational/develop.json` reference, and the already-genericized `*Reference:*` codegen note (names a workflow, not a hub path). Preamble / Devcontainer / Repository Layout references are in non-verbatim sections, untouched. ## Verification - `python3 spec/validate.py` - OK (21 cataloged). - `python3 spec/audit.py --selftest` - PASS. - CRLF preserved; rule text unchanged, only hub-only path references removed. Downstream verbatim copies read stale until re-vendored, riding the re-vendor wave already in flight (no extra cycle). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
ptr727
added a commit
that referenced
this pull request
Jul 25, 2026
## Promote develop to main Three governance/doc-only changes, all squashed to develop and Copilot-clean: - **#425** - Add Copilot review guidance for byte-locked carried fleet content (new `## Reviewing Carried Fleet Content` in `.github/copilot-instructions.md` + interim decline-pointer + `files.json` manifest entry). Root-cause fix for the recurring Copilot false positives PlexCleaner#880 flagged. - **#426** - Drop incidental catalog paths from verbatim AGENTS sections (restate the codegen bullet behaviorally; drop the two redundant `catalog/...` pointers). Finishes #422's genericization. - **#427** - Add verbatim `## Durable Knowledge and Self-Improvement` section (promoted from the non-carrying preamble; broadened to the self-improvement duty). Declared in `files.json` + `section-model.md`. No code or workflow changes - documentation and spec only, so no release fires on merge. ## Verification - `python3 spec/validate.py` - OK. - `python3 spec/audit.py --selftest` - PASS. 🤖 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.
The verbatim sweep (#420) exposed - via the PlexCleaner convergence (#880) - that the canonical AGENTS sections carried hub-local content that breaks on byte-carry. This makes them carry-clean before finmod/ESPHome converge.
needs:list innormalize()(same treatment as the action pin) so a correctly-subsettedgithub-releasebyte-matches - an unvendoredneedsname fails the workflow to load, so pruning is mandatory. Selftest added.appliesTo: *so the 3 cross-references to it (Foundational Principles, Branching Model, Release Model) resolve in every repo.audit.pylists a repo's undeclared H2 sections as an advisory so the reconciliation is surfaced (verified on ESPHome-Config: it lists its custom sections). A repo may still carry its own project-specific sections.Verified: validate + selftest + markdownlint green; the needs-mask and undeclared-advisory each have coverage.