Add Copilot review guidance for byte-locked carried fleet content - #425
Merged
Conversation
Carried verbatim sections cannot be edited downstream without breaking the fleet byte-match audit, so every Copilot flag on a reference inside them to a not-carried path (hub-only infra or the other workflow model's files) is a guaranteed false positive that recurs on every re-vendor. Tell the reviewer, via the file Copilot consults, that such references are intentional while genuine defects are still worth raising, and give agents a canned decline-pointer for the propagation window. Declare the new section in files.json so the audit enforces it downstream. 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 repository's governance/audit framework by adding explicit GitHub Copilot review guidance for byte-locked, template-carried ("carried fleet") content, and then wiring that new guidance into the spec baseline so downstream repos are audit-checked for its presence.
Changes:
- Add a new
.github/copilot-instructions.mdsection describing how to review byte-locked carried fleet content (what to ignore vs. what to still flag). - Add a reply-body convention bullet to help close false-positive review threads consistently during propagation.
- Update
spec/files.jsonso the new section is audited as required baseline content.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
spec/files.json |
Adds "Reviewing Carried Fleet Content" to the audited required section list for .github/copilot-instructions.md. |
.github/copilot-instructions.md |
Introduces the new reviewer-facing guidance section and a corresponding decline-pointer under reply-body conventions. |
This was referenced Jul 25, 2026
ptr727
added a commit
that referenced
this pull request
Jul 25, 2026
## What Corrects the `## Reviewing Carried Fleet Content` intro added in #425. ## Why Copilot flagged it on the promotion (#428), correctly: the intro said the governance files are "byte-identical" and named "the `repo-config/` and `spec/` files", but per `spec/files.json` only AGENTS.md's rule sections are byte-locked (CODESTYLE, WORKFLOW, this file, and `secrets.json` are `intent`), and downstream repos carry only `spec/secrets.json` under `spec/` - not the directory. As written it could read as an authoritative carried-file inventory and mislead a reviewer. ## Change "byte-identical" -> "kept in sync"; the list becomes illustrative ("among them ... the `repo-config/` rulesets"); the `spec/` overstatement is dropped. The precise byte-lock claim stays where it belongs, in the next sentence about AGENTS.md rule sections. ## Verification `spec/validate.py` OK, `spec/audit.py --selftest` PASS. CRLF preserved. 🤖 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.
What
Adds a
## Reviewing Carried Fleet Contentsection to.github/copilot-instructions.md(the file GitHub Copilot consults for review context) plus a matching manifest entry inspec/files.json.Why
Surfaced by PlexCleaner#880: across the last two AGENTS.md re-vendor PRs, Copilot flagged the same class four times, every one a mandatory decline. Each was a reference inside a byte-locked verbatim section to a path or section that repo does not carry (hub-only infra, or the other workflow model's files). None can be fixed locally - editing the text breaks the
audit.pybyte-match. Two layers police the same text with conflicting authority and the reviewer is simply never told the text is immutable, so it re-litigates audit-governed prose on every re-vendor.This is the root-cause fix (option 1 of three proposed): tell the reviewer, once, fleet-wide, via the file it actually reads.
Changes
spec/section-model.md/audit.py, since downstream copies do not carry them): a reference inside byte-locked fleet text to a not-carried path is intentional, not a broken link; a genuine substantive defect is still worth raising as a template-level finding.files.jsondeclares the new section so section-presence is audit-enforced downstream.Deferred (tracked separately): option 2 - restate the remaining incidental template-only paths left as prose inside verbatim AGENTS.md sections; keep the load-bearing cross-model
repo-config/operational/develop.json.Verification
python3 spec/validate.py- OK (21 cataloged, new section resolves).python3 spec/audit.py --selftest- PASS.🤖 Generated with Claude Code