Conversation
## What Adds a `## Reviewing Carried Fleet Content` section to `.github/copilot-instructions.md` (the file GitHub Copilot consults for review context) plus a matching manifest entry in `spec/files.json`. ## Why Surfaced by [PlexCleaner#880](ptr727/PlexCleaner#880 (comment)): 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.py` byte-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 - **New reviewer-facing section**, self-contained (no reference to the hub-only `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. - **Interim decline-pointer** under "Reply-body conventions" so agents can close a false-positive thread with a canned citation during the propagation window (before every repo re-vendors this file). - **`files.json`** declares the new section so section-presence is audit-enforced downstream. - Two self-description lines updated to keep the file's "intentionally narrow" inventory accurate. 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. - CRLF preserved on both files; no AGENTS.md verbatim text touched. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
## 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>
## What Adds a new **verbatim** `## Durable Knowledge and Self-Improvement` section to AGENTS.md (declared in `spec/files.json` and `spec/section-model.md` in the same change), and removes the superseded preamble line. ## Why The rule "durable guidance belongs in the committed docs, not agent memory" lived only in the AGENTS.md **preamble** - a non-verbatim zone that never carries to downstream repos. The gap showed up concretely: a fleet agent wrote a rule to its local `memory.md` instead of proposing it into AGENTS.md, and had to be re-reminded. Promoting the rule to a verbatim section makes it carry to every repo, and broadens it to the full self-improvement duty. ## Changes - **New verbatim section**, two bullets: (1) durable knowledge - a rule, contract, gotcha, or pattern to repeat/avoid - lives in a committed governance file, never in agent memory, which holds only environment-specific nuance and in-flight session state; (2) keep the governance current as you work - record durable lessons in the docs as part of the change, propose upstream where the doc is carried, fold good patterns in and design bad ones out. - **Removed** the redundant preamble line (avoids same-file content duplication). - **`files.json`** declares the section `verbatim`; **`section-model.md`** table gains its row - per section-model.md's "adding a section" rule, all three change together. Design: the self-improvement duty says "propose the change upstream" (behavior, not destination) so it complies with the carried-files rule; DSC-clean wording. Now 17 verbatim / 2 intent sections. ## Verification - `python3 spec/validate.py` - OK (the new verbatim section resolves in the hub AGENTS.md). - `python3 spec/audit.py --selftest` - PASS. - CRLF preserved on all three files. Downstream copies add the section on next re-vendor, riding the wave already in flight. 🤖 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 documentation/spec governance updates from develop to main, extending the carried governance model with a new verbatim AGENTS section and adding reviewer guidance for byte-locked carried content, with corresponding spec manifest updates.
Changes:
- Add a new verbatim
## Durable Knowledge and Self-Improvementsection toAGENTS.md, and update the section model/spec baseline to require it. - Add
## Reviewing Carried Fleet Contentguidance to.github/copilot-instructions.md, and declare the new section inspec/files.json. - Remove remaining hub-only
catalog/...prose references from verbatim AGENTS sections to reduce downstream carry false-positives.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| spec/section-model.md | Adds the new AGENTS section to the section-fidelity table. |
| spec/files.json | Updates the baseline to require the new AGENTS section and the new Copilot-instructions section. |
| AGENTS.md | Introduces the new durable-knowledge verbatim section and removes the old preamble line; genericizes a few verbatim references. |
| .github/copilot-instructions.md | Adds a carried-content review section and an explicit decline-pointer for false positives. |
## 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>
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.
Promote develop to main
Three governance/doc-only changes, all squashed to develop and Copilot-clean:
## Reviewing Carried Fleet Contentin.github/copilot-instructions.md+ interim decline-pointer +files.jsonmanifest entry). Root-cause fix for the recurring Copilot false positives PlexCleaner#880 flagged.catalog/...pointers). Finishes Genericize verbatim sections for clean carry; mask needs; section advisories #422's genericization.## Durable Knowledge and Self-Improvementsection (promoted from the non-carrying preamble; broadened to the self-improvement duty). Declared infiles.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