saturley-hall · Sep 9, 2026 · Sep 3, 2026
@@ -66,11 +66,11 @@ be merge-blocking.
 
 ## Migrated AIConfigurator Snapshot
 
-The full AIC source import preserves `python/aisimulate/CODEOWNERS` and
-`python/aisimulate/.github/codeowners/` as inactive provenance. GitHub only
-discovers CODEOWNERS at the repository root, `.github/`, or `docs/`, so the
-generated root file in this PR is the only active repository policy. The root
-policy routes changes to those preserved ownership artifacts to AISimulate
-Infra plus maintainers to keep the active and historical policies from being
+The full AIC source import preserves `python/aisimulate/.github/codeowners/` as
+inactive provenance, but its generated `CODEOWNERS` file is not retained.
+GitHub only discovers CODEOWNERS at the repository root, `.github/`, or `docs/`,
+so the generated root file is the only active repository policy. The root
+policy routes changes to the preserved ownership tooling to AISimulate Infra
+plus maintainers to keep the active and historical policies from being
 confused. The DevOps team is not listed in the active policy and is never a
 required code-owner approver.
@@ -9,6 +9,9 @@ areas:
   - label: maintainers
     github_team: "@ai-dynamo/access-aisimulate-maintain"
     path_globs:
+      - AGENTS.md
+      - CODE_OF_CONDUCT.md
+      - DEVELOPMENT.md
       - LICENSE
       - THIRD_PARTY_NOTICES.md
       - README.md
@@ -171,6 +174,10 @@ shared:
     owners: [infra, maintainers]
   - glob: SECURITY.md
     owners: [infra, maintainers]
+  - glob: AGENTS.md
+    owners: [infra, maintainers]
+  - glob: DEVELOPMENT.md
+    owners: [infra, maintainers]
   - glob: .gitattributes
     owners: [infra, maintainers]
   # Imported AIC repository metadata is inactive in this monorepo, but changes
@@ -190,12 +197,6 @@ shared:
     owners: [infra, maintainers]
   - glob: python/aisimulate/.pre-commit-config.yaml
     owners: [infra, maintainers]
-  - glob: python/aisimulate/AGENTS.md
-    owners: [infra, maintainers]
-  - glob: python/aisimulate/DEVELOPMENT.md
-    owners: [infra, maintainers]
-  - glob: python/aisimulate/SECURITY.md
-    owners: [infra, maintainers]
   - glob: python/aisimulate/eslint.config.js
     owners: [infra, maintainers]
   - glob: python/aisimulate/pyproject.toml
@@ -212,8 +213,6 @@ shared:
     owners: [infra, maintainers]
   - glob: python/aisimulate/.github/workflows/codeowners.yml
     owners: [infra, maintainers]
-  - glob: python/aisimulate/CODEOWNERS
-    owners: [infra, maintainers]
   - glob: .github/codeowners/
     owners: [infra, maintainers]
   - glob: .github/workflows/codeowners.yml

@@ -140,7 +140,6 @@ def test_representative_routing_contract() -> None:
         INFRA,
         MAINTAINERS,
     }
-    assert _owners("python/aisimulate/CODEOWNERS") == {INFRA, MAINTAINERS}
     assert _owners("crates/core/deny.toml") == {
         FPE,
         MOCKER,
@@ -150,6 +149,9 @@ def test_representative_routing_contract() -> None:
     }
     assert _owners("deny.toml") == {INFRA, MAINTAINERS}
     assert _owners("CODEOWNERS") == {INFRA, MAINTAINERS}
+    assert _owners("AGENTS.md") == {INFRA, MAINTAINERS}
+    assert _owners("DEVELOPMENT.md") == {INFRA, MAINTAINERS}
+    assert _owners("CODE_OF_CONDUCT.md") == {MAINTAINERS}
     assert _owners("README.md") == {MAINTAINERS}
     assert _owners("SECURITY.md") == {INFRA, MAINTAINERS}
     assert _owners("CONTRIBUTING.md") == {MAINTAINERS}

@@ -0,0 +1,121 @@
+# AGENTS
+
+This file adds explicit repository-wide development guards.
+
+## Required First Step
+
+Before making any change under:
+
+- `python/aisimulate/src/aiconfigurator/generator/**`
+
+MUST read:
+
+- `python/aisimulate/.claude/rules/generator-development.md`
+
+## Required Collector First Step
+
+Before making any change under `python/aisimulate/collector/**` MUST read:
+
+- `python/aisimulate/.claude/rules/collector/layer_permissions.md` (layer
+  permission table, module boundary, dispatch-vs-skip rule)
+- `python/aisimulate/.claude/rules/collector/failure_handling.md`
+  (observe-don't-predict doctrine, escalation decision tree)
+- For case YAML work:
+  `python/aisimulate/.claude/rules/collector/case_authoring.md`
+
+For adding a new Collector operation, additionally follow
+`python/aisimulate/.claude/skills/aic-collector-op-development/SKILL.md`
+(consumer-contract, case-identity, deduplication, and validation gates). Skills are procedural
+runbooks; if a skill and a `python/aisimulate/.claude/rules/` file ever
+disagree, the rule file wins.
+
+## Required Third-Party Attribution
+
+Before adding code or other content copied, adapted, translated, or
+substantially derived from an external project, MUST:
+
+- Identify the upstream repository, immutable commit or tag, original path,
+  and applicable license. This applies to source code, tests, configuration
+  files, patches, fixtures, documentation, and generated derivatives.
+- Preserve all applicable upstream copyright, license, attribution, and NOTICE
+  material, and mark modified files as modified when the upstream license
+  requires it.
+- Record the source URL and revision in the file header or an adjacent README.
+  For formats that cannot carry comments, use an adjacent attribution or
+  license file that is included in distributions.
+- Add an entry to the root `THIRD_PARTY_NOTICES.md` identifying the derived
+  files, upstream source and immutable revision, copyright owner, applicable
+  license, and whether the files were modified. The root notice is canonical;
+  keep `python/aisimulate/THIRD_PARTY_NOTICES.md` byte-identical so the notice
+  is included in Python distributions. Run
+  `python3 scripts/check_packaged_legal_files.py` after either copy changes.
+- Do not hand-edit generated attribution artifacts. Update their source or
+  generation process instead.
+
+The repository's Apache-2.0 license and NVIDIA copyright header do not replace
+an upstream license or attribution requirement. Do not label third-party code
+as exclusively NVIDIA-authored. If the source, revision, license, compatibility,
+or required notice is unclear, stop and request maintainer or Open Source Review
+Board guidance before committing the derived content. This is a required gate,
+not optional documentation.
+
+## Cursor Cloud specific instructions
+
+### Project overview
+
+AISimulate is a Python and Rust CLI/SDK for predicting LLM serving behavior and
+optimizing inference deployment configurations. See `README.md` for details.
+
+### Environment setup
+
+Python dependencies are managed via `uv` with the
+`python/aisimulate/uv.lock` lockfile. The project environment lives at
+`python/aisimulate/.venv/`.
+
+- **Install/refresh deps:**
+  `uv sync --project python/aisimulate --extra dev`
+- **Performance data:** Current op profiles are parquet files under
+  `python/aisimulate/src/aiconfigurator_core/systems/data/<system>/<family>/<backend>/<version>/`
+  and are checked in directly. Legacy `*.txt` perf files, when present, use Git
+  LFS; run `git lfs pull` only when working with those legacy assets.
+
+### Lint / Test / Run
+
+- **Lint:** `python/aisimulate/.venv/bin/ruff check --config python/aisimulate/pyproject.toml python/aisimulate tests`
+  and `python/aisimulate/.venv/bin/ruff format --check --config python/aisimulate/pyproject.toml python/aisimulate tests`
+  (see `DEVELOPMENT.md`)
+- **Unit tests:** `python/aisimulate/.venv/bin/pytest -c python/aisimulate/pytest.ini python/aisimulate/tests -m unit`
+  (no external deps or LFS data needed)
+- **Build tests (PR subset):** `python/aisimulate/.venv/bin/pytest -c python/aisimulate/pytest.ini python/aisimulate/tests -m "unit or build"`
+  (requires LFS data for the `build`-marked tests)
+- **CLI:** `aiconfigurator cli generate --model-path Qwen/Qwen3-32B-FP8 --total-gpus 8 --system h200_sxm` (works without LFS data)
+### Known environment caveats
+
+1. **Legacy LFS data:** `github-cloud.githubusercontent.com` may be blocked by
+   network egress restrictions. If `git lfs pull` fails, tests that explicitly
+   exercise legacy text assets may fail; current parquet-backed workflows do
+   not depend on those legacy files.
+2. **TTY tests:** 4 tests in
+   `python/aisimulate/tests/unit/cli/test_plain_output.py` may fail because the
+   agent runs in a non-TTY environment.
+3. **Rust tests:**
+   `python/aisimulate/tests/unit/sdk/test_rust_engine_step.py` requires `cargo`
+   with network access to `crates.io`. It will fail if that domain is blocked.
+4. **macOS pytest-timeout crash dialogs:** The `timeout = 120` setting in
+   `python/aisimulate/pytest.ini` uses SIGALRM by default, which triggers
+   "Python unexpectedly quit" crash reporter popups on macOS. Pass
+   `-p no:timeout` to disable it locally.
+5. **torch-dependent tests:**
+   `python/aisimulate/tests/unit/sdk/database/test_moe_dispatch.py` requires
+   `torch` (not installed in the default dev venv). Ignore it with
+   `--ignore=python/aisimulate/tests/unit/sdk/database/test_moe_dispatch.py`.
+
+## CODEOWNERS
+
+The root `CODEOWNERS` is generated from `.github/codeowners/areas.yaml` - never
+hand-edit it; CI fails on drift. Repository rules must require the `codeowners`
+check to make failures merge-blocking. If the check fails on a new directory,
+claim it in `areas.yaml`, regenerate with
+`.github/codeowners/emit_codeowners.py`, and commit every changed source and
+generated artifact together. The `aic-codeowners` skill covers all flows (who
+reviews a change, gate failures, routing changes, external contributor grants).
@@ -27,11 +27,14 @@
 # === maintainers  (@ai-dynamo/access-aisimulate-maintain) ===
 /docs/                                               @ai-dynamo/access-aisimulate-maintain
 /LICENSE                                             @ai-dynamo/access-aisimulate-maintain
+/AGENTS.md                                           @ai-dynamo/access-aisimulate-maintain
 /README.md                                           @ai-dynamo/access-aisimulate-maintain
 /SECURITY.md                                         @ai-dynamo/access-aisimulate-maintain
+/DEVELOPMENT.md                                      @ai-dynamo/access-aisimulate-maintain
 /CONTRIBUTING.md                                     @ai-dynamo/access-aisimulate-maintain
 /CONTRIBUTORS.md                                     @ai-dynamo/access-aisimulate-maintain
 /tests/conftest.py                                   @ai-dynamo/access-aisimulate-maintain
+/CODE_OF_CONDUCT.md                                  @ai-dynamo/access-aisimulate-maintain
 /THIRD_PARTY_NOTICES.md                              @ai-dynamo/access-aisimulate-maintain
 
 # === forward-pass-engine  (@ai-dynamo/aisimulate-forward-pass-engine-codeowners) ===
@@ -90,6 +93,7 @@
 
 # --- Shared ownership: multi-team (any one approves; wins via last-match) ---
 /scripts/                                            @ai-dynamo/aisimulate-infra-codeowners @ai-dynamo/access-aisimulate-maintain
+/AGENTS.md                                           @ai-dynamo/aisimulate-infra-codeowners @ai-dynamo/access-aisimulate-maintain
 /deny.toml                                           @ai-dynamo/aisimulate-infra-codeowners @ai-dynamo/access-aisimulate-maintain
 /CODEOWNERS                                          @ai-dynamo/aisimulate-infra-codeowners @ai-dynamo/access-aisimulate-maintain
 /Cargo.lock                                          @ai-dynamo/aisimulate-infra-codeowners @ai-dynamo/access-aisimulate-maintain
@@ -99,6 +103,7 @@
 /SECURITY.md                                         @ai-dynamo/aisimulate-infra-codeowners @ai-dynamo/access-aisimulate-maintain
 /docs/sweeper/                                       @ai-dynamo/aisimulate-sweeper-codeowners @ai-dynamo/access-aisimulate-maintain
 /.gitattributes                                      @ai-dynamo/aisimulate-infra-codeowners @ai-dynamo/access-aisimulate-maintain
+/DEVELOPMENT.md                                      @ai-dynamo/aisimulate-infra-codeowners @ai-dynamo/access-aisimulate-maintain
 /tests/sweeper/                                      @ai-dynamo/aisimulate-sweeper-codeowners @ai-dynamo/access-aisimulate-maintain
 /docs/aic-sync.md                                    @ai-dynamo/aisimulate-forward-pass-engine-codeowners @ai-dynamo/aisimulate-infra-codeowners @ai-dynamo/access-aisimulate-maintain
 /docs/core-api.md                                    @ai-dynamo/aisimulate-forward-pass-engine-codeowners @ai-dynamo/access-aisimulate-maintain
@@ -127,19 +132,15 @@
 /tests/test_unified_cli.py                           @ai-dynamo/aisimulate-replay-codeowners @ai-dynamo/aisimulate-sweeper-codeowners @ai-dynamo/aisimulate-forward-pass-engine-codeowners @ai-dynamo/access-aisimulate-maintain
 /crates/core/src/perfmodel/                          @ai-dynamo/aisimulate-forward-pass-engine-codeowners @ai-dynamo/access-aisimulate-maintain
 /python/aisimulate/.github/                          @ai-dynamo/aisimulate-infra-codeowners @ai-dynamo/access-aisimulate-maintain
-/python/aisimulate/AGENTS.md                         @ai-dynamo/aisimulate-infra-codeowners @ai-dynamo/access-aisimulate-maintain
 /crates/core/tests/perfmodel/                        @ai-dynamo/aisimulate-forward-pass-engine-codeowners @ai-dynamo/access-aisimulate-maintain
 /python/aisimulate/.gitignore                        @ai-dynamo/aisimulate-infra-codeowners @ai-dynamo/access-aisimulate-maintain
-/python/aisimulate/CODEOWNERS                        @ai-dynamo/aisimulate-infra-codeowners @ai-dynamo/access-aisimulate-maintain
 /python/aisimulate/pytest.ini                        @ai-dynamo/aisimulate-infra-codeowners @ai-dynamo/access-aisimulate-maintain
-/python/aisimulate/SECURITY.md                       @ai-dynamo/aisimulate-infra-codeowners @ai-dynamo/access-aisimulate-maintain
 /tests/test_stack_discovery.py                       @ai-dynamo/aisimulate-replay-codeowners @ai-dynamo/aisimulate-sweeper-codeowners @ai-dynamo/access-aisimulate-maintain
 /tests/test_host_offload_cli.py                      @ai-dynamo/aisimulate-replay-codeowners @ai-dynamo/access-aisimulate-maintain
 /python/aisimulate/.dockerignore                     @ai-dynamo/aisimulate-infra-codeowners @ai-dynamo/access-aisimulate-maintain
 /.github/workflows/codeowners.yml                    @ai-dynamo/aisimulate-infra-codeowners @ai-dynamo/access-aisimulate-maintain
 /crates/core/src/engine/timing.rs                    @ai-dynamo/aisimulate-mocker-codeowners @ai-dynamo/aisimulate-forward-pass-engine-codeowners @ai-dynamo/access-aisimulate-maintain
 /python/aisimulate/.gitattributes                    @ai-dynamo/aisimulate-infra-codeowners @ai-dynamo/access-aisimulate-maintain
-/python/aisimulate/DEVELOPMENT.md                    @ai-dynamo/aisimulate-infra-codeowners @ai-dynamo/access-aisimulate-maintain
 /python/aisimulate/pyproject.toml                    @ai-dynamo/aisimulate-forward-pass-engine-codeowners @ai-dynamo/aisimulate-sweeper-codeowners @ai-dynamo/aisimulate-replay-codeowners @ai-dynamo/aisimulate-mocker-codeowners @ai-dynamo/aisimulate-infra-codeowners @ai-dynamo/access-aisimulate-maintain
 /crates/tests/public-api/Cargo.toml                  @ai-dynamo/aisimulate-forward-pass-engine-codeowners @ai-dynamo/aisimulate-infra-codeowners @ai-dynamo/access-aisimulate-maintain
 /python/aisimulate/.coderabbit.yaml                  @ai-dynamo/aisimulate-infra-codeowners @ai-dynamo/access-aisimulate-maintain

@@ -135,4 +135,4 @@ For answers to common questions about this code of conduct, see the FAQ at
 [v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
 [Mozilla CoC]: https://github.com/mozilla/diversity
 [FAQ]: https://www.contributor-covenant.org/faq
-[translations]: https://www.contributor-covenant.org/translations
+[translations]: https://www.contributor-covenant.org/translations