diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 66091cd7..d4b93b32 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -2,39 +2,19 @@ Repository-wide instructions for GitHub Copilot. -Read [AGENTS.md](../AGENTS.md) first. It routes every standing repository rule to its canonical -document. When performing code review, load and follow the `code-review` skill in -`.github/skills/code-review/SKILL.md`, then load every language, documentation, or workflow skill -that it selects for the changed files. GitHub Copilot reads these files from the pull request's -head branch, so review the instructions in that tree. +Read [AGENTS.md](../AGENTS.md) first. It routes every standing repository rule to its canonical document. When performing code review, load and follow the `code-review` skill in `.github/skills/code-review/SKILL.md`, then load every language, documentation, or workflow skill that it selects for the changed files. GitHub Copilot reads these files from the pull request's head branch, so review the instructions in that tree. -Do not duplicate rules from `AGENTS.md`, `GOVERNANCE.md`, `CODESTYLE.md`, or `WORKFLOW.md` here. -This file contains only Copilot-specific bootstrap and output requirements. +Do not duplicate rules from `AGENTS.md`, `GOVERNANCE.md`, `CODESTYLE.md`, or `WORKFLOW.md` here. This file contains only Copilot-specific bootstrap and output requirements. ## Commit Messages and Pull Request Titles -Use an imperative subject of at most 72 characters with no trailing period. Use US English and -title case with lowercase short bind words. Do not add `Co-Authored-By:` unless requested. Do not -put a release-bump magnitude in the title. The full contract is in -[GOVERNANCE.md "Pull Request Title and Commit Message Conventions"](../GOVERNANCE.md#pull-request-title-and-commit-message-conventions). +Use an imperative subject of at most 72 characters with no trailing period. Use US English and title case with lowercase short bind words. Do not add `Co-Authored-By:` unless requested. Do not put a release-bump magnitude in the title. The full contract is in [GOVERNANCE.md "Pull Request Title and Commit Message Conventions"](../GOVERNANCE.md#pull-request-title-and-commit-message-conventions). ## Reviewing Carried Fleet Content -Follow the fidelity declared for the file. A byte-locked reference to shared infrastructure that -this repository does not carry is intentional, not a broken link. Raise substantive defects in -canonical content, but locate the fix at its canonical source instead of proposing a local edit. - -`.github/skills/`, and in the hub `.claude-plugin/fleet-skills/`, are generated by the hub's -`scripts/build_dist.py` from its `.agents/skills/`, so a defect in either is fixed in the source or -the generator and never in the copy. A defect inside an include region, the text between the -marker lines `` and `` that every copy -carries as its authored source does, is fixed in the hub under the heading that key names, since -the region is generated from that heading's body and the key's path resolves against the hub's -root rather than this repository's copy of the same file. Where that heading's body is itself a -region, the fix sits one hop further, under the heading its own key names. Post no review comment -on a file under `.github/skills/` or, in the hub, `.claude-plugin/fleet-skills/`. When the pull -request changes the file the fix belongs in, comment on that file instead, and otherwise state -the finding in the review summary. +Follow the fidelity declared for the file. A byte-locked reference to shared infrastructure that this repository does not carry is intentional, not a broken link. Raise substantive defects in canonical content, but locate the fix at its canonical source instead of proposing a local edit. + +`.github/skills/`, and in the hub `.claude-plugin/fleet-skills/`, are generated by the hub's `scripts/build_dist.py` from its `.agents/skills/`, so a defect in either is fixed in the source or the generator and never in the copy. A defect inside an include region, the text between the marker lines `` and `` that every copy carries as its authored source does, is fixed in the hub under the heading that key names, since the region is generated from that heading's body and the key's path resolves against the hub's root rather than this repository's copy of the same file. Where that heading's body is itself a region, the fix sits one hop further, under the heading its own key names. Post no review comment on a file under `.github/skills/` or, in the hub, `.claude-plugin/fleet-skills/`. When the pull request changes the file the fix belongs in, comment on that file instead, and otherwise state the finding in the review summary. ## GitHub Copilot Review Runbook @@ -42,29 +22,13 @@ For every review: 1. Read the full pull request diff and count its changed files. 2. Follow `.github/skills/code-review/SKILL.md` and every skill it selects. -3. Publish every supported finding. Never suppress a finding or place it in a low-confidence or - hidden findings block. -4. Use an inline comment when a changed line can anchor the finding. Use the review body only when - no valid inline anchor exists. +3. Publish every supported finding. Never suppress a finding or place it in a low-confidence or hidden findings block. +4. Use an inline comment when a changed line can anchor the finding. Use the review body only when no valid inline anchor exists. 5. End the review body with the exact machine-readable marker required by the `code-review` skill. -The review automation is `scripts/pr_review.py`, run from a hub checkout. Use its `status`, `wait`, -`comment`, and `reply --resolve` commands instead of reconstructing GraphQL queries or copying -review identifiers by hand. Use `comment` for a suppressed-finding answer in the pull request -conversation. Its status gate verifies the current head, diff coverage, output shape, inline -threads, body-only findings, and required checks. - -A formal review with no findings is complete only when it covers the current head and full diff -coverage is stated for the change set that head has. The round covering the head states it, or the -newest round that states it at all does and the pull request changes the same set of files at -both commits, which is the only condition under which a statement carries forward. Only that -newest round is consulted, so an older round whose change set does match carries nothing. A round reporting partial coverage -of the diff blocks the merge, and so does a refusal, a coverage statement that does not reach -this head, meaning absent from every round or carried by none because the change set moved or -could not be compared, an unrecognized output shape, an unresolved thread, or a body-only -finding. -Re-run the loop after every fix -push. Never infer review completion from `mergeStateStatus: CLEAN`. +The review automation is `scripts/pr_review.py`, run from a hub checkout. Use its `status`, `wait`, `comment`, and `reply --resolve` commands instead of reconstructing GraphQL queries or copying review identifiers by hand. Use `comment` for a suppressed-finding answer in the pull request conversation. Its status gate verifies the current head, diff coverage, output shape, inline threads, body-only findings, and required checks. + +A formal review with no findings is complete only when it covers the current head and full diff coverage is stated for the change set that head has. The round covering the head states it, or the newest round that states it at all does and the pull request changes the same set of files at both commits, which is the only condition under which a statement carries forward. Only that newest round is consulted, so an older round whose change set does match carries nothing. A round reporting partial coverage of the diff blocks the merge, and so does a refusal, a coverage statement that does not reach this head, meaning absent from every round or carried by none because the change set moved or could not be compared, an unrecognized output shape, an unresolved thread, or a body-only finding. Re-run the loop after every fix push. Never infer review completion from `mergeStateStatus: CLEAN`. Review effort is user-controlled. The automation observes `Lite`, `Balanced`, or `Max`, including an inherited `Default ()`, and never selects or changes the setting. Effort does not determine coverage or completion. A request can complete without a `copilot_work_started` event, so absence of that event is not a stalled-review verdict. When `wait` returns `PENDING` with `requested=yes`, report the state and rerun `wait` for another bounded interval by default. Do not clear the request automatically because it may be active. If the maintainer directs a retry, remove Copilot in the pull request UI, add it again, and rerun `wait`. This recovery replaces only the review request and never changes the effort setting. @@ -110,5 +74,4 @@ Review effort is user-controlled. The automation observes `Lite`, `Balanced`, or ## When in Doubt -Stop and report the uncertainty. Do not guess at an instruction, suppress a possible finding, or -claim coverage that the review did not perform. +Stop and report the uncertainty. Do not guess at an instruction, suppress a possible finding, or claim coverage that the review did not perform.