Skip to content

Modernize agent instructions and prioritize security-first reviews #8296

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Max (maxtropets) merged 12 commits into from
Sep 8, 2026
Merged

Modernize agent instructions and prioritize security-first reviews #8296

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
82d67f1
Modernize and consolidate agent instructions
Copilot Sep 7, 2026
be6800f
Prioritize security and safety in CCF review guidance
Copilot Sep 7, 2026
567be0a
Generalize security review guidance without incident references
Copilot Sep 7, 2026
6f12a04
Make ASCII-only code and instruction policy explicit
Copilot Sep 7, 2026
4d0d389
Merge branch 'main' into copilot/list-agent-faced-instructions
maxtropets Sep 7, 2026
24bf263
Reference Keep a Changelog in release instructions
achamayou Sep 7, 2026
e6e469f
Align ASCII policy and exempt Lean source
achamayou Sep 8, 2026
821d045
Make ASCII policy regression script executable
achamayou Sep 8, 2026
1549fe6
Restore review instruction metadata format
Copilot Sep 8, 2026
03a95fb
Merge branch 'main' into copilot/list-agent-faced-instructions
achamayou Sep 8, 2026
40a9b68
Merge branch 'main' into copilot/list-agent-faced-instructions
maxtropets Sep 8, 2026
bb2e0d7
Merge branch 'main' into copilot/list-agent-faced-instructions
achamayou Sep 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
195 changes: 47 additions & 148 deletions .github/copilot-instructions.md
View file
Open in desktop

Large diffs are not rendered by default.

25 changes: 14 additions & 11 deletions .github/instructions/changelog.instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,30 +1,33 @@
---
applyTo:
- "CHANGELOG.md"
applyTo: "CHANGELOG.md,python/pyproject.toml"
---

# CHANGELOG entries

These instructions apply both when writing and when reviewing changes to `CHANGELOG.md`.
Use [Keep a Changelog 1.0.0](https://keepachangelog.com/en/1.0.0/) format, with the CCF-specific rules below.

These instructions apply when writing or reviewing changelog entries and SDK release-version changes. Unrelated changes to `python/pyproject.toml` do not require a release bump.

## Selecting the release section

Before adding an entry, determine the latest published CCF release from the git `ccf-<version>` tags or github.com/microsoft/CCF releases. Do not infer release status from the contents of `CHANGELOG.md` alone.
Before adding an entry, identify the target branch's release line and whether it is a stable maintenance line or a prerelease/development line. Use the branch context and published `ccf-<version>` releases/tags; do not select the repository-wide newest release across unrelated release lines, infer publication from `CHANGELOG.md` alone, or rely on an incomplete local tag list. Confirm ambiguous publication status against GitHub releases.

- Every entry must be placed under a concrete Semantic Versioning release section.
- If the first release section in `CHANGELOG.md` is newer than the latest published release, treat it as the next release and add the entry to the appropriate existing subsection.
- If the first release section has already been published, create a new section above it by incrementing the patch component of the latest published release. Add the matching link definition using the existing `https://github.com/microsoft/CCF/releases/tag/ccf-<version>` convention.
- Use concrete Semantic Versioning release sections, not `Unreleased`.
- If the first section is an unpublished next release for the target line, use it.
- On a stable maintenance line, if the first section is already published, create the next patch section above it using the latest published stable release on that line. Add the matching `https://github.com/microsoft/CCF/releases/tag/ccf-<version>` link definition.
- For prerelease/development lines, follow an explicit release target rather than inventing a patch, minor, major, or prerelease increment. If the target line, next version, or publication status cannot be established, ask for clarification before editing release metadata.
- Whenever a new release section is created, update `project.version` in `python/pyproject.toml` to the same version. The first version in `CHANGELOG.md` and `project.version` must always match.
- When reviewing a changelog addition, verify the release status, section selection, and version synchronisation above.
- When reviewing release metadata, verify section selection and version synchronisation. Report unavailable publication evidence as a validation limitation, not a guessed release status.

## Pull request references

Every new or modified entry must include a reference to the pull request that introduced the change and to the relevant issues(s) that the PR closes, in the form `(#1234)` at the end of the entry, matching the existing convention.
Each new or modified entry must reference the introducing PR using `(#1234)`. Preserve original PR references when correcting an existing entry; include the current PR when it introduces an additional change. Issue references are optional in changelog entries; closing references belong in the PR description.

When reviewing, flag any added or modified bullet under an `Added`, `Changed`, `Fixed`, `Removed`, or similarly named section that does not include such a `(#<number>)` reference, and ask the author to add the corresponding PR number. This applies to entries directly under top-level version sections and in nested subsections such as `Developer API` / `C++` / `Added`.
- Before a PR number exists, omit the reference temporarily and report that it must be added once the PR exists, before merge. Never invent a number or add a fake numeric placeholder.
- When reviewing a PR, flag touched entries missing the relevant PR reference, including nested entries. A reference to an issue alone does not satisfy the PR-reference requirement.

Do not flag:

- Section headings, version headings, or release-highlights blockquotes.
- Pre-existing entries that the diff does not touch.
- Entries that already cite at least one PR number, even if they reference additional issues or commits as well.
- Entries that already cite the relevant introducing PR, whether or not they also reference issues or commits.
151 changes: 69 additions & 82 deletions .github/instructions/reviewing.instructions.md
View file
Open in desktop

Large diffs are not rendered by default.

85 changes: 39 additions & 46 deletions .github/skills/formatting-and-linting/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,49 +6,42 @@ description: "Format and lint CCF changes. Use when choosing or running checks f

# Formatting and linting

`scripts/ci-checks.sh` orchestrates all formatting and linting checks by running individual scripts concurrently. You can run all checks at once, or run only the scripts relevant to the files you changed.

To run **all** checks with auto-fix: `scripts/ci-checks.sh -f`

To run **only the checks you need**, use the individual scripts below based on the file types you modified. When a script supports `-f`, you **must** use it to auto-fix issues. When `-f` is not available, run the script and read its error output to determine what changes are needed.

## Scripts with auto-fix (`-f`)

These scripts accept a `-f` flag that automatically corrects issues. Always run them with `-f`:

| Script | Run with | File types | Tool |
| --------------------------------- | ------------------------------------ | ----------------------------------------------------------------------------- | ------------------------ |
| `scripts/cpp-format-checks.sh` | `scripts/cpp-format-checks.sh -f` | `.h`, `.hpp`, `.c`, `.cpp`, `.cc` in `include/`, `src/`, `samples/` | clang-format |
| `scripts/python-format-checks.sh` | `scripts/python-format-checks.sh -f` | `.py` in `tests/`, `python/`, `scripts/`, `tla/` | black |
| `scripts/python-lint-checks.sh` | `scripts/python-lint-checks.sh -f` | `.py` in `python/`, `tests/` | ruff |
| `scripts/prettier-checks.sh` | `scripts/prettier-checks.sh -f` | `.ts`, `.js`, `.md`, `.yaml`, `.yml`, `.json` (excludes `tests/sandbox/`) | prettier |
| `scripts/cmake-format-checks.sh` | `scripts/cmake-format-checks.sh -f` | `CMakeLists.txt` and `.cmake` files in `cmake/`, `samples/`, `src/`, `tests/` | gersemi |
| `scripts/release-notes-checks.sh` | `scripts/release-notes-checks.sh -f` | Release notes in `CHANGELOG.md` | extract-release-notes.py |

## Scripts without auto-fix

These scripts only report problems. Run them and read their error output to determine what manual changes are needed:

| Script | Run with | File types | What to look for in the output |
| -------------------------------- | -------------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `scripts/shellcheck-checks.sh` | `scripts/shellcheck-checks.sh` | `.sh` files (excludes `3rdparty/`) | shellcheck warnings and errors with line numbers and fix suggestions |
| `scripts/python-types-checks.sh` | `scripts/python-types-checks.sh` | `.py` in `python/` | mypy type errors with file, line number, and expected types |
| `scripts/includes-checks.sh` | `scripts/includes-checks.sh` | Public headers under `include/ccf/` (`.h`, `.hpp`) | Public/private include violations in files under `include/ccf/`, missing `namespace ccf` in public headers, or unused exported headers |
| `scripts/copyright-checks.sh` | `scripts/copyright-checks.sh` | All source files | Files missing or with incorrect copyright notice headers |
| `scripts/openapi-checks.sh` | `scripts/openapi-checks.sh` | `.json` in `doc/schemas/` | OpenAPI schema validation errors from swagger-cli |
| `scripts/todo-checks.sh` | `scripts/todo-checks.sh` | All tracked files | Unacceptable comments that must be removed or resolved |
| `scripts/ascii-checks.sh` | `scripts/ascii-checks.sh` | Source files (excludes `3rdparty/`, prose docs, and intentionally non-ASCII files) | Non-ASCII characters that must be replaced with their plain ASCII equivalents |

## Which scripts to run for each file type

| If you modified | Run these scripts |
| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| C/C++ source or headers (`.h`, `.hpp`, `.c`, `.cpp`, `.cc`) | `cpp-format-checks.sh -f`, `includes-checks.sh`, `copyright-checks.sh`, `ascii-checks.sh` |
| Python files (`.py`) | `python-format-checks.sh -f`, `python-lint-checks.sh -f`, `python-types-checks.sh`, `copyright-checks.sh`, `ascii-checks.sh` |
| TypeScript/JavaScript (`.ts`, `.js`) | `prettier-checks.sh -f`, `copyright-checks.sh`, `ascii-checks.sh` |
| Markdown (`.md`) | `prettier-checks.sh -f` |
| YAML (`.yaml`, `.yml`) | `prettier-checks.sh -f`, `ascii-checks.sh` |
| JSON (`.json`) | `prettier-checks.sh -f`, `openapi-checks.sh` (if in `doc/schemas/`), `ascii-checks.sh` |
| CMake files (`CMakeLists.txt`, `.cmake`) | `cmake-format-checks.sh -f`, `ascii-checks.sh` |
| Shell scripts (`.sh`) | `shellcheck-checks.sh`, `copyright-checks.sh`, `ascii-checks.sh` |
| Release notes (`CHANGELOG.md`) | `release-notes-checks.sh -f`, `prettier-checks.sh -f` |
## Scope and prerequisites

Run commands from the repository root. `scripts/ci-checks.sh` runs the individual checks concurrently, including a build-configuration check. Use the global instructions' validation policy to choose targeted local checks or the full suite.

The Copilot setup workflow runs `scripts/setup-ubuntu-ci-checks.sh` for Ubuntu formatting/lint prerequisites. Some checks use `uvx` or npm to obtain tools at runtime and need network access. The test-bucket check additionally requires the full CMake configure prerequisites; the setup workflow does not install those.

## Check first, fix only task-owned changes

- Run scripts without `-f` initially. Success is exit status 0; inspect failure output to distinguish changed-file issues, unrelated failures, and environment blockers.
- The scripts generally scan whole directories or tracked files, not just the diff. Selecting a script by file type does not restrict which files it may rewrite.
- For auto-fix, use the existing underlying formatter/linter with explicit changed-file paths and the same version/configuration used by the script. Only fix files or hunks owned by the task; preserve existing user edits.
- Use a script's `-f` mode only after verifying its complete write scope is intended. Do not run repository-wide auto-fix as a default.
- Inspect the resulting diff and rerun the applicable check. Do not remove unrelated edits to make checks pass. Report blockers and unrelated failures under the global validation policy.

## Check inventory

Each command below is under `scripts/`. This table is a routing guide; the scripts own exact file coverage, exclusions, tool versions, and options. When changing that coverage, update this guide too. Include cross-cutting checks (copyright, disallowed comments, ASCII) when applicable.

| Script | Relevant changes | Tool/check | Supports auto-fix |
| ------------------------- | ------------------------------------------------------------ | -------------------------------------------------- | ----------------- |
| `cpp-format-checks.sh` | C/C++ in `include/`, `src/`, `samples/` | clang-format | `-f` |
| `python-format-checks.sh` | Python in `tests/`, `python/`, `scripts/`, `tla/` | black | `-f` |
| `python-lint-checks.sh` | Python in `python/`, `tests/` | ruff | `-f` |
| `python-types-checks.sh` | Python SDK | mypy | No |
| `prettier-checks.sh` | TS, JS, Markdown, YAML, JSON (excluding `tests/sandbox/`) | prettier | `-f` |
| `cmake-format-checks.sh` | CMake files | gersemi | `-f` |
| `release-notes-checks.sh` | `CHANGELOG.md` (also run prettier) | extract-release-notes.py | `-f` |
| `shellcheck-checks.sh` | Shell scripts outside `3rdparty/` | shellcheck | No |
| `includes-checks.sh` | Public C++ headers and their uses | Public/private include and exported-header checks | No |
| `copyright-checks.sh` | Source files | Copyright notices | No |
| `openapi-checks.sh` | JSON under `doc/schemas/` | openapi-spec-validator | No |
| `todo-checks.sh` | Tracked files | Disallowed comments | No |
| `ascii-checks.sh` | Source/config files and agent-instruction Markdown | ASCII policy and grandfathered Unicode lines | No |
| `ascii-policy-tests.sh` | ASCII policy/checker changes | ASCII policy regression tests | No |
| `test-buckets-checks.sh` | CMake test registration, defaults, or `tests/ci-buckets.txt` | Fresh configure and CI bucket inventory comparison | No |

Some report-only scripts accept `-f` for interface compatibility without changing files. For Rust or other file types not covered by a formatter above, consult their existing build/CI configuration rather than introducing a new tool.

The ASCII check includes Rust and TLA+, but exempts Lean source files (`*.lean`). Existing Unicode is grandfathered by exact line hashes, not file-wide exemptions. Do not extend the grandfathered hashes to accept new Unicode.
Loading