From 4a4b1f5b2c51fef2fab7e670b808975a6cc90b0b Mon Sep 17 00:00:00 2001 From: Vivek Khandelwal Date: Tue, 4 Aug 2026 12:45:39 +0000 Subject: [PATCH 1/3] ci(copilot): add Copilot custom instructions for public-disclosure review Copilot code review already runs on every PR and push here (the "CoPilot Review" repository ruleset), but the repo ships no custom instructions, so Copilot reviews each diff with no knowledge that this repository is the public half of a public/private split. Its own review footer has been asking for these files. PR #285 is the case this is meant to catch: an internal design doc and a contributor-specific demo guide, including a lab machine hostname, reached public main and had to be deleted after the fact. Reverting does not unpublish anything, so the check has to happen before merge. - .github/copilot-instructions.md: repository-wide. States the public/private boundary and that the plugin entry-point group means customer-specific material is never required here, then enumerates six categories to flag. Mirrors aorta-internal's CLAUDE.md rule 4 onto the public side. - .github/instructions/docs.instructions.md: scoped to docs/** and READMEs via applyTo, since prose is where this has actually gone wrong. Audience test plus checks for example commands, pasted output, cross-links, and deletions that leave dangling references. Both files carry an explicit "do not add real names, hostnames, or internal URLs here" rule and an allow-list of things that are already public (product and arch names, public ROCm links, aorta-internal issue pointers, docs/plans/, built-in mitigation names, artifactory-cdn.amd.com URLs in docker/), because a reviewer that flags established practice trains people to ignore it. These instructions are advisory: Copilot posts comments and cannot block a merge, and it reads instructions from the PR head branch. Enforcement would need a required status check, which this PR does not add. Co-authored-by: Cursor --- .github/copilot-instructions.md | 101 ++++++++++++++++++++++ .github/instructions/docs.instructions.md | 53 ++++++++++++ 2 files changed, 154 insertions(+) create mode 100644 .github/copilot-instructions.md create mode 100644 .github/instructions/docs.instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 000000000..a82f9b37e --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,101 @@ +# Copilot instructions -- ROCm/aorta + +## This repository is public + +`ROCm/aorta` is a public repository. Everything that reaches `main` -- source, +docs, recipes, test fixtures, sample logs, commit messages -- is world-readable +and permanent in git history. Reverting a leak does not unpublish it. + +AORTA's private counterpart, `ROCm/aorta-internal`, owns the customer-escalation +workloads, NDA'd reproducer sources, and the mitigation harness. The two sides +meet only through the public `aorta.workloads` entry-point group, and this +repository's plugin system exists precisely so downstream and private workloads +can register from outside. **Customer-specific material is therefore never +required here for the platform to work.** If a diff seems to need it, that is the +signal that the change belongs on the private side. + +Treat every pull request as a disclosure review as well as a code review. When +something in a diff looks like it belongs on the private side, raise it +explicitly, name the category below that it falls under, and say whether the fix +is to relocate it to `aorta-internal` or to redact it in place. Prefer raising a +borderline case over staying silent: a false positive costs a review comment, a +false negative is public forever. + +## What must not land in this repository + +1. **Customer and partner identity.** Names, codenames, abbreviations, ticket + IDs, or logos of external customers and partners -- in code, comments, + docstrings, docs, recipe names, cell names, fixture filenames, or test data. + This includes indirect identification: a workload named after the customer's + product, or a model/config combination unique enough to identify them. + +2. **Customer workload material.** Reproducer sources, model definitions, + training or inference scripts, hyperparameters, dataset names or paths, and + model architecture details that arrived from a customer escalation. These live + in the owning workload directory on the private side. + +3. **Real captured environments and logs.** Verbatim environment-variable dumps, + `aorta env probe` snapshots, training logs, loss curves, step timings, or + profiler output taken from a real customer or partner run. Fixtures and + examples in this repository should be synthetic or drawn from AMD's own + hardware. Watch for these arriving as large `.json` / `.log` / `.txt` + additions under `tests/`, `examples/`, or `docs/`. + +4. **Internal infrastructure identifiers.** Lab, dev, and CI machine hostnames; + internal IP addresses and subnets; cluster, partition, or queue names; + internal dashboard, wiki, or document-store URLs; and absolute paths that + embed a user's home directory or an internal mount. A setup guide or example + command that only works on one specific machine is the usual way these arrive + -- rewrite it against a placeholder. + +5. **Non-public container images.** Image tags or digests from AMD-internal or + customer-gated registries. Only images a member of the public can actually + pull belong in committed Dockerfiles, recipes, and docs. + +6. **Internal-only planning material.** Design documents, roadmaps, escalation + post-mortems, and status reports written for an internal audience. Public + planning documents are welcome (see the "expected here" list below); the test + is the intended audience and the content, not the file's location. + +## This file is public too + +Do not add real customer names, codenames, hostnames, or internal URLs to this +file or to any other instructions file, whether as a deny-list, an example, or a +"do not use this string" note. Doing so publishes the exact value the rule exists +to protect. Describing the *shape* of a sensitive value is the most any file in +this repository can carry. The authoritative list lives on the private side. + +## What is expected here, and should not be flagged + +These are all normal in this repository. Flagging them produces noise and trains +reviewers to ignore disclosure comments. + +- **AMD product and architecture names** -- `MI300X`, `MI350X`, `MI355X`, + `MI450X`, `gfx942`, `gfx1250`, ROCm and HIP version numbers. Public. +- **Links to public repositories and docs**, including `ROCm/rocm-systems`, + `mirage`, `rocjitsu`, and `rocm.docs.amd.com`. +- **Cross-references to `aorta-internal` issue numbers.** Pointing at a private + issue by number is established practice here (see + `tests/probe/test_recurring_issue_regression.py`). The pointer is fine; what + must not follow it across is the customer-identifying content behind it. +- **`docs/plans/`.** A legitimate home for planning documents written for a + public audience, such as feature rubrics tied to public issues. +- **Public mitigation and environment-variable names** -- `tf32_off`, + `hsa_xnack`, `HSA_NO_SCRATCH_RECLAIM`, and the rest of the built-in registry. + These are published debugging knobs, not customer information. +- **Contributor names, emails, and GitHub handles** in git metadata, CODEOWNERS, + and changelogs. +- **`docker/` package URLs on `artifactory-cdn.amd.com`.** These predate these + instructions and are already on `main`; do not raise them as new findings. + Newly added credentials, tokens, or auth headers alongside them are in scope. + +## How to raise a finding + +Comment on the specific line, name the category number, and state the remedy. +For example: "Category 4 -- this example command hardcodes a lab hostname, so it +only works on one machine and publishes its name. Suggest a placeholder such as +`` with the requirement described in prose." + +If a diff mixes platform work with customer-specific material, say which files +are safe to merge and which need to move, so the author can split the pull +request rather than rework it wholesale. diff --git a/.github/instructions/docs.instructions.md b/.github/instructions/docs.instructions.md new file mode 100644 index 000000000..d824e9146 --- /dev/null +++ b/.github/instructions/docs.instructions.md @@ -0,0 +1,53 @@ +--- +applyTo: "docs/**,**/README.md" +--- + +# Disclosure review for prose + +Narrative files are where private material has actually reached public `main` in +this repository, because prose carries the incidental detail that code does not: +the machine someone ran it on, the internal document that explains why, the +customer the investigation was really about. Apply the categories in +`.github/copilot-instructions.md`, and additionally check the following. + +## Is this document written for a public reader? + +A page belongs here only if a ROCm user outside AMD could act on it. Ask who the +audience is: + +- **Reproducible by anyone** -- flag nothing. Setup guides, CLI walkthroughs, + schema references, and design notes for published features are the point of + `docs/`. +- **Reproducible only by the author** -- flag it. A walkthrough pinned to one + developer's host, container name, absolute home-directory path, or scratch + mount is a private artifact even when nothing in it is formally confidential. + The remedy is usually to parameterise the specifics, not to delete the page. +- **Written for an internal audience** -- flag it. Escalation narratives, status + updates addressed to an internal team, and design documents for unpublished + work belong in `aorta-internal`. Public planning documents tied to public + issues are fine and live in `docs/plans/`. + +## Checks specific to prose + +- **Example commands and shell blocks.** Every host, path, container name, + registry, and image tag in a fenced block is published. Prefer a placeholder + (``, `$HOME`, ``) with the requirement stated in prose + over a literal value that happened to work on one machine. +- **Pasted output.** Sample terminal output, `env probe` snapshots, and log + excerpts should be synthetic or from AMD hardware, and trimmed to the lines + that illustrate the point. A full paste tends to carry hostnames, absolute + paths, and environment details nobody reviewed. +- **Cross-links.** Links must resolve for an anonymous reader. A link to a + private repository path, an internal wiki, or a document store is both a broken + link and a disclosure of the internal structure. Naming a private issue by + number is fine; linking into private content is not. +- **Deletions that leave dangling references.** When a page is removed because it + should not have been public, the same pull request has to drop every reference + to it -- other docs, README links, and module docstrings. A stale link tells a + reader exactly what was withdrawn and invites them to go looking for it. + +## Do not rewrite technical substance + +These instructions cover what is safe to publish, not how the documentation +should read. Do not use a disclosure review to argue for restructuring a page, +changing its tone, or expanding its coverage. From 9042a3d0f59f8efa25b503e71fff9f754db4a1fd Mon Sep 17 00:00:00 2001 From: Vivek Khandelwal Date: Tue, 4 Aug 2026 12:52:05 +0000 Subject: [PATCH 2/3] ci(copilot): don't let the audience test waive line-level disclosure checks Copilot's own review of this PR caught it: the "reproducible by anyone" bullet said "flag nothing", which reads as a blanket waiver on the whole page rather than on its audience. A broadly useful doc can still leak a hostname, an absolute path, or an internal image tag in one example, so that wording would have suppressed exactly the findings the file exists to produce. Scope the audience test to whether the page belongs in a public repository, and say explicitly that it never waives the category checks on the contents. Co-authored-by: Cursor --- .github/instructions/docs.instructions.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/.github/instructions/docs.instructions.md b/.github/instructions/docs.instructions.md index d824e9146..fc2feabca 100644 --- a/.github/instructions/docs.instructions.md +++ b/.github/instructions/docs.instructions.md @@ -13,11 +13,15 @@ customer the investigation was really about. Apply the categories in ## Is this document written for a public reader? A page belongs here only if a ROCm user outside AMD could act on it. Ask who the -audience is: - -- **Reproducible by anyone** -- flag nothing. Setup guides, CLI walkthroughs, - schema references, and design notes for published features are the point of - `docs/`. +audience is. This test decides whether the *page* belongs in a public repository; +it never waives the line-level checks. A broadly useful document can still leak a +hostname, an absolute path, or an internal image tag in a single example, so apply +the categories to the contents either way. + +- **Reproducible by anyone** -- the page itself is in scope for `docs/`, so raise + no objection to its presence. Setup guides, CLI walkthroughs, schema + references, and design notes for published features are the point of this + directory. Still review its individual lines. - **Reproducible only by the author** -- flag it. A walkthrough pinned to one developer's host, container name, absolute home-directory path, or scratch mount is a private artifact even when nothing in it is formally confidential. From 5a4476f1bd7037b9109c9008fcd07f711549c3c2 Mon Sep 17 00:00:00 2001 From: Vivek Khandelwal Date: Tue, 4 Aug 2026 12:56:31 +0000 Subject: [PATCH 3/3] ci(copilot): repeat the "this file is public too" rule in the docs instructions Second catch from Copilot's review of this PR: the rule only lived in the repo-wide instructions, but the docs-scoped file is the one that will be edited when someone adds a worked example of a check -- which is exactly the moment a real hostname or customer name gets pasted in to illustrate the point. Co-authored-by: Cursor --- .github/instructions/docs.instructions.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/.github/instructions/docs.instructions.md b/.github/instructions/docs.instructions.md index fc2feabca..8f3841078 100644 --- a/.github/instructions/docs.instructions.md +++ b/.github/instructions/docs.instructions.md @@ -50,6 +50,14 @@ the categories to the contents either way. to it -- other docs, README links, and module docstrings. A stale link tells a reader exactly what was withdrawn and invites them to go looking for it. +## This file is public too + +Every rule above applies to this file. When illustrating a check, describe the +shape of the offending value rather than quoting a real hostname, path, image +tag, or customer name -- pasting one here publishes the exact value the rule +exists to protect. See the same section in +`.github/copilot-instructions.md`. + ## Do not rewrite technical substance These instructions cover what is safe to publish, not how the documentation