Split the agent instruction set into AGENTS.md and GOVERNANCE.md - #28
Merged
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## develop #28 +/- ##
========================================
Coverage 44.96% 44.96%
========================================
Files 25 25
Lines 3398 3398
Branches 259 259
========================================
Hits 1528 1528
Misses 1824 1824
Partials 46 46 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
There was a problem hiding this comment.
Pull request overview
This PR aligns PhotoCleaner’s carried governance docs with the hub’s split model by introducing GOVERNANCE.md as the topical rulebook and slimming AGENTS.md into a router/entry-point, while retargeting cross-references across the repository to the new locations.
Changes:
- Add
GOVERNANCE.mdcontaining the full set of cross-cutting governance sections (with repo-specificDevcontainerandRepository Layout). - Reduce
AGENTS.mdto context/delegation guidance plus a task-to-section map intoGOVERNANCE.md. - Update documentation cross-references across governance/workflow/audit docs from
AGENTS.mdanchors toGOVERNANCE.mdanchors and labels.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| WORKFLOW.md | Retarget governance cross-references (notably branching model and governance authority) to GOVERNANCE.md. |
| repo-config/README.md | Update branching-model references to point at GOVERNANCE.md instead of AGENTS.md. |
| GOVERNANCE.md | Introduce the new split governance rulebook with topical sections and repo-specific intent sections. |
| CODESTYLE.md | Retarget process-rule references to GOVERNANCE.md and relocate two repo rules into CODESTYLE where appropriate. |
| AUDIT.md | Update prose authorities and branching-model links to GOVERNANCE.md. |
| AGENTS.md | Slim down to entry-point router plus context/delegation guidance. |
| .github/copilot-instructions.md | Retarget PR review contract references to GOVERNANCE.md and add carried-fleet-review guidance. |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.
Suppressed comments (1)
WORKFLOW.md:13
- The last sentence contradicts the prior clause in the same paragraph: it says
GOVERNANCE.mdis authoritative where it overlaps this document, but then saysAGENTS.mdwins on conflicts. IfGOVERNANCE.mdis the authority in overlaps, the conflict-resolution sentence should nameGOVERNANCE.md.
> **Canonical scope.** This document is authoritative for the workflow contract and test methodology (sections 3 to 6). The conventions in section 2 and the release policy also live in `GOVERNANCE.md` ("Workflow YAML Conventions" and "Release Model"), which is authoritative where the two overlap. Section 2 restates them so this file reads on its own. On any conflict in that overlap, `AGENTS.md` wins.
ptr727
added a commit
that referenced
this pull request
Aug 3, 2026
* Split the agent instruction set into AGENTS.md and GOVERNANCE.md The hub restructured the agent instruction set into a slim router plus a topical rule book, and this repo still carried the pre-split single file. The audit reported GOVERNANCE.md absent, both AGENTS.md verbatim regions missing, and all ten of its sections as undeclared. AGENTS.md now carries only the repo intro and the two verbatim sections the baseline declares for it, Context and Delegation Discipline and Where the Rules Live. GOVERNANCE.md carries the eighteen topical sections, the sixteen verbatim ones byte-identical to the canonical, with Devcontainer and Repository Layout written for this repo as the section model requires. Repository Onboarding and Conformance is hub-only and is not carried. Every rule the old AGENTS.md held was probed against the canonical by its distinctive phrase before the file was replaced. Two were not covered and moved to CODESTYLE.md rather than being dropped: the full post-change set (the clean-compile task plus dotnet test plus dotnet husky run), and the shared README.md and HISTORY.md header. .github/copilot-instructions.md gains the Reviewing Carried Fleet Content section, which tells a reviewer that a reference inside byte-locked text to a path this repo does not carry is intentional. Cross-references in AUDIT.md, CODESTYLE.md, WORKFLOW.md, repo-config/README.md, and the runbook are retargeted to the sections' new home. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * Trim the trailing blank line at the end of GOVERNANCE.md markdownlint MD012 flagged two consecutive blank lines at the end of the file. The generator appended the Repository Layout block with its own trailing newline on top of the file's, and the local lint run that would have caught it was made on a branch that does not carry the file. All eighteen verbatim sections still hash equal to the canonical. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * Point the WORKFLOW.md precedence claim at GOVERNANCE.md The Canonical scope callout says GOVERNANCE.md is authoritative where the two overlap and then ended by naming AGENTS.md as the tiebreak, which contradicts itself now that AGENTS.md is the router and the rule text lives in GOVERNANCE.md. The hub canonical already reads GOVERNANCE.md here; the retarget pass caught the first half of the sentence and missed the second. Swept the tree for other stale precedence claims: none. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5 (1M context) <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.
The hub restructured the agent instruction set into a slim router (
AGENTS.md) plus a topical rule book (GOVERNANCE.md), and this repo still carried the pre-split single file. This is the largest class in the conformance sweep and the only LETTER-class file finding.The split
AGENTS.md(73 lines, down from 57 KB) carries the repo intro plus the two sectionsspec/files.jsondeclares for it.GOVERNANCE.mdcarries the eighteen topical sections.Repository Onboarding and Conformanceis hub-only perspec/section-model.mdand is not carried.DevcontainerandRepository Layoutare the twointentsections, so both are written for this repo: this repo ships no devcontainer, and the layout describes its own tree.All eighteen verbatim regions hash byte-identical to the canonical after EOL normalization, and neither file carries an undeclared section.
Nothing was dropped
spec/section-model.md"Migrating a repo onto the split" warns that re-vendoring over the whole file silently deletes local additions written after a fault the fleet has never seen, and that a similarity heuristic is confidently wrong in exactly the direction that loses content. So every rule in the old file was probed against the canonical by its distinctive phrase. All but two resolved to a hub section that had reworded or absorbed them.The two that did not are moved to
CODESTYLE.mdrather than dropped:dotnet testanddotnet husky runalso run before commit.CODESTYLE.md"Clean-Compile Verification" covers the first step only, so the other two had no home.README.md/HISTORY.mdheader. This is fleet law, but it lives inspec/readme-structure.md, which is hub-only and not carried, so a downstream pointer would dangle. Kept as a repo rule under "Markdown and Spelling". Raised with the hub as a spec gap (AUDIT.mdsection 9).Cross-references
Ten sections moved file, so every reference to them was retargeted:
AUDIT.md,CODESTYLE.md(4 sites plus the cspell one-liner reference),WORKFLOW.md,repo-config/README.md, and three sites in the runbook. Reference-link labels renamedagents-*togovernance-*and the definition blocks re-alphabetized. NoAGENTS.md#anchor and no[agents]label remains anywhere in the repo..github/copilot-instructions.mdalso gains Reviewing Carried Fleet Content, which exists to stop a reviewer reporting a byte-locked reference to a path this repo does not carry as a broken link. Adapted from the canonical to nameGOVERNANCE.md, since the hub's own copy still describes the pre-splitAGENTS.md; raised with the hub.Verification
6501479; both files carry no undeclared section.editorconfig-checkerexits 0.AGENTS.md#anchors or[agents]reference labels remain.Part of the conformance sweep against the hub baseline (
audit run 2026-08-01T14:29:05Z | hub 6501479).