diff --git a/.github/AGENTS.md b/.github/AGENTS.md index 4e5e4ae..c4b73b2 100644 --- a/.github/AGENTS.md +++ b/.github/AGENTS.md @@ -1,46 +1,44 @@ - - - -# .github - -## Purpose -`.github` contains GitHub project automation: issue forms, pull request templates, snapshot provenance enforcement, release workflow, and CI verification definitions. - -## Key Files -| File | Description | -|------|-------------| -| `pull_request_template.md` | Default PR body, including exact snapshot provenance labels parsed by the guard. | -| `scripts/check_snapshot_provenance.py` | Base/head blob comparison plus PR decision validation. | - -## Subdirectories -| Directory | Purpose | -|-----------|---------| -| `ISSUE_TEMPLATE/` | Numbered `.yml` issue forms and chooser config (see `ISSUE_TEMPLATE/AGENTS.md`). | -| `scripts/` | Repository governance scripts, including snapshot provenance validation. | -| `workflows/` | GitHub Actions workflow definitions (see `workflows/AGENTS.md`). | - -## For AI Agents - -### Working In This Directory -- Treat workflow changes as CI-affecting; keep dependency installation and verification commands aligned with `pyproject.toml`. -- Keep issue and PR templates concise and consistent with repository scope. - -### Testing Requirements -- Validate YAML syntax for workflow or issue template edits. -- For workflow changes, mirror commands locally where practical before relying on CI. -- Run `pytest tests/test_governance.py tests/test_release_workflow.py` when provenance scripts, workflow wiring, or PR declarations change. - -### Common Patterns -- `test.yml` is both normal CI and the local reusable workflow called by a tag release. -- Snapshot runtime PRs require one validated provenance decision; non-PR runs still enforce append-only provenance content. - -## Dependencies - -### Internal -- `pyproject.toml` defines the Python versions, package dependencies, and tools invoked by workflows. -- `tests/` contains the suite run by CI. - -### External -- GitHub Actions runners and standard GitHub issue/PR template formats. - - +# Repository Automation + +Parent scope: [repository](../AGENTS.md). + +| Path | Contract | +| --- | --- | +| [workflows](workflows/AGENTS.md) | CI quality gates and tag-driven release ordering | +| [ISSUE_TEMPLATE](ISSUE_TEMPLATE/AGENTS.md) | Numbered issue forms and chooser configuration | +| `pull_request_template.md` | Default PR template and machine-parsed snapshot decision labels | +| `scripts/check_snapshot_provenance.py` | Base/head Git-blob comparison and PR declaration validation | +| `scripts/clean_wheel_agent_acceptance.py` | Supplied wheel acceptance in temporary home/CWD/venv | + +## Provenance Guard + +The guard compares the supplied base/head commits, not just working-tree content. +Changes anywhere under `src/pt_snap_cli/snapshot/`, including `AGENTS.md`, trigger +the PR decision requirement. Supply exactly one `Snapshot provenance decision:` +with `updated` or `no-update`. `updated` requires new nonblank provenance content; +`no-update` requires one specific `Snapshot provenance no-update reason:` and no +provenance-file change. Placeholder text and duplicate declarations fail. + +Existing provenance lines cannot be rewritten, reordered or deleted. This +content check also runs on main pushes and tag releases. Preserve PR `edited` +events so correcting a declaration can rerun CI. + +## Installed-Wheel Acceptance + +The acceptance script installs a supplied wheel offline into a temporary venv +with system dependencies available, and verifies that `pt_snap_cli` resolves +inside that venv. It clears source/catalog/focus environment overrides and uses +temporary HOME/CWD for helper installation and import-created focus. + +It then checks help, bundled catalog/install status, capabilities, trusted fixture +import/reuse, overview and a peak query. This is executable CLI acceptance, not a +live model evaluation. The script accepts only the expected committed +`snapshot_with_empty_cache.pkl` path; run fixture provenance verification first. + +## Change Together + +Keep guard labels, the default PR template, and workflow inputs aligned. Run +`pytest tests/test_governance.py tests/test_release_workflow.py` from the repository +root for governance/wiring changes. Read scripts before invoking them: the guard +is read-only, while wheel acceptance creates an environment and loads trusted +pickle data. Workflow/package changes also use the source packaging contracts. diff --git a/.github/ISSUE_TEMPLATE/AGENTS.md b/.github/ISSUE_TEMPLATE/AGENTS.md index bb7204a..aa7ee9a 100644 --- a/.github/ISSUE_TEMPLATE/AGENTS.md +++ b/.github/ISSUE_TEMPLATE/AGENTS.md @@ -1,44 +1,21 @@ - - - -# ISSUE_TEMPLATE - -## Purpose -`ISSUE_TEMPLATE` contains structured GitHub issue forms for bugs, documentation requests, feature requests, questions, and template chooser configuration. - -## Key Files -| File | Description | -|------|-------------| -| `01-bug-report.yml` | Form for reproducible defects and environment details. | -| `02-feature-request.yml` | Form for proposed enhancements. | -| `03-documentation.yml` | Form for documentation improvements or corrections. | -| `04-question.yml` | Form for usage questions. | -| `config.yml` | GitHub issue chooser configuration and valid contact links. | - -## Subdirectories -| Directory | Purpose | -|-----------|---------| -| None | Issue templates are flat YAML files. | - -## For AI Agents - -### Working In This Directory -- Keep issue forms scoped to this Python CLI project. -- Preserve valid GitHub issue form YAML structure. -- Ordering is controlled by numbered filenames; `config.yml` has no `issue_templates` key. - -### Testing Requirements -- Validate YAML syntax and run `pytest tests/test_governance.py` after path/schema edits. - -### Common Patterns -- Forms collect structured fields rather than relying on free-form Markdown only. - -## Dependencies - -### Internal -- Repository README/docs provide canonical terminology for issue prompts. - -### External -- GitHub issue form YAML schema. - - +# Issue Forms + +Parent scope: [automation](../AGENTS.md). + +| File | Purpose | +| --- | --- | +| `01-bug-report.yml` | Reproduction and environment details | +| `02-feature-request.yml` | Proposed behavior and use case | +| `03-documentation.yml` | Documentation errors or improvements | +| `04-question.yml` | Usage questions | +| `config.yml` | Blank-issue policy and contact links | + +Numbered filenames control chooser ordering. Preserve GitHub issue-form +`name`, `description`, and structured `body` fields; `config.yml` does not have +an `issue_templates` key. Keep prompts aligned with CLI, SnapshotDB and agent-skill +terminology in the README/docs. Contact links must lead to enabled destinations. + +The PR template is `../pull_request_template.md`, outside this directory. Changes +to form names/paths or chooser schema require YAML validation and +`pytest tests/test_governance.py` from the repository root; the governance suite +checks the expected form set and supported template placement. diff --git a/.github/workflows/AGENTS.md b/.github/workflows/AGENTS.md index c4d38d7..2959c6d 100644 --- a/.github/workflows/AGENTS.md +++ b/.github/workflows/AGENTS.md @@ -1,48 +1,49 @@ - - +# CI and Release Lifecycles -# workflows +Parent scope: [automation](../AGENTS.md). -## Purpose -`workflows` contains GitHub Actions definitions for continuous integration and release automation. +## Test Workflow -## Key Files -| File | Description | -|------|-------------| -| `test.yml` | Reusable provenance, lint, type, test-matrix, coverage, build, and wheel smoke checks. | -| `release.yml` | Tag workflow that gates build and publication on the tagged commit's reusable quality workflow. | +`test.yml` runs for main pushes, main-targeted PR opened/synchronize/reopened/edited +events, and `workflow_call`. Provenance, lint and Python test-matrix jobs are +independent. Concurrency is keyed by GitHub ref and superseded runs are cancelled. -## Subdirectories -| Directory | Purpose | -|-----------|---------| -| None | Workflow YAML files are flat. | +| Job/step | Gate | +| --- | --- | +| Snapshot provenance | Full Git history; base/head comparison; PR decision required only in PR mode | +| Lint & Format | Python 3.13, editable dev install, Ruff, Black, basedpyright with the selected interpreter | +| Test matrix | Python 3.10–3.13; fixture provenance first, then pytest with branch coverage | +| Overall coverage | `pyproject.toml` fail-under 90 with branches enabled | +| Critical runtime coverage | Import backend 90; simulated allocator 88; snapshot mutator 84, checked independently | +| Python 3.13 packaging | Upload coverage, build wheel, run clean-wheel Agent acceptance | -## For AI Agents +Coverage reporting writes `.coverage`/`coverage.xml`; building writes `dist/` and +intermediates. Dependency installation/build isolation may access the network. +The [acceptance script](../scripts/clean_wheel_agent_acceptance.py) uses temporary +paths but imports a reviewed executable fixture. These are more than YAML checks. -### Working In This Directory -- Keep workflow Python versions and commands aligned with `pyproject.toml`. -- Treat release workflow edits as high-impact and verify syntax carefully. -- Do not bypass tests, lint, type checks, or publishing safeguards without explicit instruction. -- Keep snapshot provenance inputs and declaration parsing aligned with `.github/scripts/check_snapshot_provenance.py` and the PR template. -- Keep release validation before PyPI publication; release notes and package version must be validated in `build`. +## Release Workflow -### Testing Requirements -- Validate YAML syntax. -- Run equivalent local commands when changing CI command sequences. -- Run `pytest tests/test_governance.py tests/test_release_workflow.py` for provenance or release workflow changes. +`release.yml` triggers on `v*` tag pushes and enforces: -### Common Patterns -- Workflows install the package with development extras before verification. -- The test workflow defines independent provenance, lint, and Python-version test jobs that may run concurrently. -- Release ordering is `quality` -> `build` -> `publish` -> `github-release`; the local reusable workflow is resolved from the tag commit. +`quality` → `build` → `publish` → `github-release`. -## Dependencies +- `quality` invokes `./.github/workflows/test.yml` at the tagged commit. +- `build` fetches full history for setuptools-scm, builds sdist/wheel, verifies + the installed wheel's version matches the tag, runs `pt-snap --version`, and + extracts a nonempty matching `CHANGELOG.md` section before uploading artifacts. +- `publish` uses the protected `pypi` environment and OIDC trusted publishing. +- `github-release` publishes the same distributions and extracted notes only + after PyPI publication succeeds. -### Internal -- `pyproject.toml` defines package metadata, dev extras, and tool configuration. -- `tests/` and source files are exercised by CI. +Do not substitute a different commit's CI result or publish before version/notes +validation. For non-PR provenance checks, tag runs compare against the prior tag +(or root commit fallback); pushes use the before SHA with a root fallback. -### External -- GitHub Actions hosted runners and packaging/publishing actions. +## Verification - +Review `pyproject.toml`, both workflow YAMLs, the provenance/acceptance scripts and +`tests/test_release_workflow.py` together when changing execution order. Validate +YAML and run `pytest tests/test_governance.py tests/test_release_workflow.py` from +the repository root. Full CI tests the matrix and installed wheel; static tests +do not prove a release environment is configured or a publication occurred. diff --git a/AGENTS.md b/AGENTS.md index 2132622..bbcae61 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,170 +1,111 @@ # AGENTS.md -This is the repository-wide entry point for coding agents. Keep durable project -facts here; user-facing behavior belongs in `README.md` and `docs/`. +Repository-wide guidance for `pt-snap-cli`, a Python 3.10+ package for importing, +splitting, and analyzing PyTorch memory snapshots. User-facing behavior belongs +in `README.md`, `README_zh.md`, and `docs/`; `CLAUDE.md` delegates here. -## Project Scope +## Start Here -`pt-snap-cli` is a Python 3.10+ package for importing, splitting, inspecting, -and querying PyTorch memory snapshots. It exposes a Typer CLI and a Python API -over shared service-layer behavior. +Read the nearest scoped guide before editing. Each guide links its children; +follow the hierarchy rather than copying local rules into this file. -## Development Commands - -Run these commands from the repository root. - -- Install for local development: `pip install -e .` -- Install development dependencies: `pip install -e ".[dev]"` -- Run all tests: `pytest` -- Run one file: `pytest tests/test_cli.py` -- Run one test: `pytest tests/test_cli.py -k test_version_flag` -- Lint: `ruff check .` -- Check formatting: `black --check .` -- Apply formatting: `black .` -- Type check: `python -m basedpyright --pythonpath "$(python -c 'import sys; print(sys.executable)')"` - (covers all of `src/pt_snap_cli`, including `snapshot/`; the gate is zero - errors; API/model/representation Any/Unknown checks are errors and other - warnings are informational. Do not add a snapshot - `executionEnvironments` downgrade.) - -`tests/run_tests.sh` is tied to a developer-specific Conda path and writes -coverage reports under `test_reports/`; use direct `pytest` commands unless -that local environment is intentionally available. - -Local-only directories (`.pt-snap/` written by `pt-snap focus`/`pt-snap import`, -`tmp/`, `.tmp/`, `.worktrees/`) are ignored by Git and excluded from Ruff and -Black in `pyproject.toml`, so the root-level lint commands above stay stable -when they exist. - -## Scoped Guidance - -| Scope | Guide | Responsibility | +| Scope | Guide | Ownership | | --- | --- | --- | -| GitHub automation | [.github/AGENTS.md](.github/AGENTS.md) | Issue/PR templates, provenance guard, CI, and release workflows | -| User documentation | [docs/AGENTS.md](docs/AGENTS.md) | English/Chinese guides, API docs, navigation, and legal evidence | -| Package source | [src/AGENTS.md](src/AGENTS.md) | Installable package boundaries and source-layout rules | -| Tests | [tests/AGENTS.md](tests/AGENTS.md) | Cross-surface contracts, service/query/runtime suites, and reviewed executable fixtures | -| Benchmarks | [benchmarks/AGENTS.md](benchmarks/AGENTS.md) | Import and SQLite performance measurement with temporary outputs | -| Agent skills | [skills/AGENTS.md](skills/AGENTS.md) | Helper routing, installation approval, Ascend NPU collection, and read-only memory-diagnostic workflows | +| Package/build boundary | [src](src/AGENTS.md) | Setuptools discovery, installed assets, versioning | +| Runtime and adapters | [pt_snap_cli](src/pt_snap_cli/AGENTS.md) | CLI/API, focus, Context, and subsystem routing | +| Tests | [tests](tests/AGENTS.md) | Contracts, resource ownership, fixture gate, focused suites | +| Agent workflows | [skills](skills/AGENTS.md) | Routing, setup, collection, diagnostics, packaged copies | +| User documentation | [docs](docs/AGENTS.md) | Bilingual guides, API references, legal evidence | +| Automation | [.github](.github/AGENTS.md) | Provenance guard, issue forms, CI and release | +| Performance | [benchmarks](benchmarks/AGENTS.md) | Opt-in import and SQLite measurements | ## Runtime Topology -| Surface | Entry point | Responsibility | +| Surface | Entry/registration | Implementation | | --- | --- | --- | -| CLI | `src/pt_snap_cli/cli.py` via `pt_snap_cli.cli:_safe_call` | Typer commands for focus, import, split, metadata, capabilities, overview, query, reports, config, and skill install/list | -| CLI groups/output | `src/pt_snap_cli/cli_reports.py`, `cli_skills.py`, `cli_output.py` | Report/skill command registration and shared terminal/JSON error adaptation; registered by `cli.py` | -| Python API | `src/pt_snap_cli/api.py` (`SnapshotAnalyzer`) | Programmatic focus, query, and metadata facade | -| Product services | `src/pt_snap_cli/core/` | Shared focus, import, split, query, report, metadata, and error semantics | -| Database access | `src/pt_snap_cli/context.py` | Read-only SQLite validation, connection management, and device discovery | -| Query engine | `src/pt_snap_cli/query/` | YAML loading, registry, parameter validation, SQL rendering/execution, and result mapping | -| Snapshot runtime | `src/pt_snap_cli/snapshot/` | First-party pickle/JSON representation, replay, database import, and slicing | -| Library models | `src/pt_snap_cli/models/` | Dataclass models and allocator event/block enums | - -Installed scripts and package data are declared in `pyproject.toml`. Query -templates under category subdirectories are included by -`query/templates/*/*.yaml`. - -## Repository Invariants - -### CLI and Python API - -- Keep normalized CLI and `SnapshotAnalyzer` behavior in shared API/core - services; adapters may format output differently but must not redefine focus, - query, metadata, or error semantics. -- Update `tests/test_contract_cli_api.py` when a shared CLI/API capability or - normalized result changes. - -### Focus and database selection - -- `Config.resolve_focus()` resolves the database in this order: explicit path, - `PT_SNAP_DB_PATH`, nearest ancestor `.pt-snap/focus.json`, then legacy global - config at `~/.config/pt-snap-cli/config.json`. -- Query device selection is explicit device, focused device, then the first - device discovered from `trace_entry_` tables. -- `Context` opens SQLite with `mode=ro` and validates the `dictionary` table. - Do not introduce writes into the analysis path. - -### Query templates - -- Packaged templates live under `src/pt_snap_cli/query/templates//*.yaml`. -- `query/config.py` owns YAML parsing and parameter validation; - `query/registry.py` recursively loads templates into the singleton registry; - `query/executor.py` renders with Jinja2 `StrictUndefined` and injects device - table names before executing through `Context`. -- Templates that differ by SnapshotDB callstack layout declare - `query_variants.v1` / `query_variants.v2` in the same YAML entry and share - description, parameters, and `output_schema`. Unaffected templates keep a - single `query`. `Context` detects the layout from read-only column/table - checks (with `pt_snap_metadata` as an auxiliary check) and - `QueryExecutor` selects the matching SQL. Conflicting or damaged layouts - leave `callstack_layout` unset and fail only variant templates. Do not - persist layout in `focus.json` or migrate databases on open. -- Field semantics (`units`, `metric_semantics`, `scope`, `denominator`, - `sentinel`, `interpretation_limits`) and template-level `semantics_version` - ride the same YAML → config → registry → core → CLI/API path as `choices`. - Do not add a second schema. `semantics_version` is distinct from YAML - `version` and SnapshotDB / callstack layout; v1/v2 SQL variants share one - contract. Unannotated templates remain valid with `column`/`type` only. -- When template metadata or behavior changes, review the YAML, config, registry, - executor, `core/query_service.py`, CLI/API presentation, and focused tests - together. - -### Agent skills - -- Author skills under `skills//SKILL.md`. Keep the packaged copy at - `src/pt_snap_cli/bundled_skills//SKILL.md` identical so wheel installs - can run `pt-snap skill install`. -- `SkillService` prefers `PT_SNAP_SKILLS_DIR` when set, then the repository - `skills/` tree in a source checkout, then packaged copies. Default install writes the shared - `~/.agents/skills` tree (Cursor, OpenCode, current Codex, and other - Agent Skills hosts) plus Claude's independent `~/.claude/skills` or - `$CLAUDE_CONFIG_DIR/skills`. `--target cursor` and `--target codex` keep - the host-native extras; `--dir` covers anything else. List reports - `installed`, `outdated`, or `missing`. Unfiltered `pt-snap skill uninstall` - (no `--target`, `--project`, or `--dir`) removes every installed or outdated - copy that list would report and that contains `SKILL.md`, across all - built-in hosts and both scopes. A same-named path without `SKILL.md` - aborts the whole unfiltered uninstall before any deletion. - `uninstall_skills(all_locations=True)` rejects dest_dir, hosts, and - scope other than `user`. `--target` / `--project` / `--dir` keep the - narrower mutation destinations. - Skill management is CLI-only. - -### Snapshot import and split - -- Pickle input is trusted-code execution, not a sandbox. Never load an - untrusted fixture or snapshot merely to inspect it. -- Import writes and validates metadata on a temporary database before - publication. When focus update is requested, publication retains a rollback - link until the atomic focus write succeeds; reported failure preserves the - previous destination. -- Split requires exactly one positive strategy (`--slices` or - `--max-entries`), an absent destination, replay-validates generated slices, - and publishes the staged directory without replacement. -- `src/pt_snap_cli/snapshot/PROVENANCE.md` is append-only. The guard compares - base/head Git blobs on PRs, main pushes, and releases; snapshot-runtime PRs - additionally require the exact provenance decision in the default PR template. +| Console script | `pyproject.toml` → `pt_snap_cli.cli:_safe_call` | `cli.py` root commands; `cli_reports.py` and `cli_skills.py` groups; `cli_output.py` shared output/errors | +| Python API | `api.py:SnapshotAnalyzer` | Session focus, template queries, capabilities, overview, metadata | +| Product behavior | `core/` services | Shared resolution, validation, results and errors; import/split publication; CLI-only skill management | +| Analysis | `Context` → `query/` | Read-only SQLite, layout detection, YAML contracts, Jinja rendering, result mapping | +| Snapshot runtime | `snapshot/` via core import/split | Trusted representation loading, allocator replay, database adaptation, slicing | +| Agent integration | Authored `skills/` → packaged `bundled_skills/` | Host-loaded workflows calling the CLI; no MCP server or console entry point | + +## Development and Checks + +Run from the repository root using the intended Python environment. Installing +changes that environment and may download dependencies: + +```bash +python -m pip install -e ".[dev]" +``` + +For an isolated worktree using dependencies already installed elsewhere, set +`PYTHONPATH="$PWD/src"` on Python/test commands so imports come from that worktree. +Do not silently repoint a shared editable installation. + +```bash +pytest tests/test_fixture_provenance.py # Before any committed-pickle loading +pytest # Or the owning focused suite +ruff check . +black --check . +python -m basedpyright --pythonpath "$(python -c 'import sys; print(sys.executable)')" +git diff --check +``` + +- Type checking covers all `src/pt_snap_cli`, including `snapshot/`. Zero errors + is the gate; warnings are informational. Preserve the file-level Any/Unknown + error gates in `api.py`, `core/models.py`, and `snapshot/representation.py`; + do not downgrade snapshot through an `executionEnvironments` exception. +- Pytest treats `ResourceWarning` and `PytestUnraisableExceptionWarning` as + errors. Ownership/teardown guidance lives in [tests](tests/AGENTS.md). +- Coverage is measured with branches enabled. The overall floor and independent + critical-file floors are documented with [CI](.github/workflows/AGENTS.md). +- `tests/run_tests.sh` assumes a developer-specific Conda path and writes + `test_reports/`; prefer direct pytest. `.pt-snap/`, `.tmp/`, `.worktrees/`, + and `tmp/` are ignored and excluded from root Ruff/Black checks. +- `python -m build` writes `dist/` and build intermediates and may download build + requirements. See [packaging](src/AGENTS.md) before using it as verification. + +## Cross-Repository Contracts + +1. **One behavior layer.** CLI and `SnapshotAnalyzer` adapters share core + semantics; update `tests/test_contract_cli_api.py` when normalized shared + results change. Skill management is CLI-only; the analyzer is not an + import/split or skill-install facade. +2. **Resolution and read-only analysis.** `Config.resolve_focus()` selects + explicit path → `PT_SNAP_DB_PATH` → nearest ancestor `.pt-snap/focus.json` → + legacy `~/.config/pt-snap-cli/config.json`. Queries select explicit device → + focused device → first discovered device. `Context` requires `dictionary` + and opens SQLite with `mode=ro`; analysis must not migrate a database or + persist detected layout into focus. +3. **Explicit resource ownership.** Analyzer `close()`/`with` ends its lifetime; + an injected cache stays caller-owned. Cache/service reuse and terminal + analyzer closure are different contracts; see [core](src/pt_snap_cli/core/AGENTS.md). +4. **Single query contract.** YAML metadata, validation, registry, executor, + services and adapters form one path. Layout-specific SQL shares a public + schema and semantic contract. Query caps, completeness and timeouts must + remain visible to callers; see [query](src/pt_snap_cli/query/AGENTS.md). +5. **Trusted input and transactional publication.** Pickle loading is code + execution, not a sandbox. Import stages and validates before publication and + includes a requested focus update in rollback handling. Split replay-validates + staged output and publishes without replacing an existing destination. +6. **Skill/source parity.** Author `skills//SKILL.md` and keep its packaged + `src/pt_snap_cli/bundled_skills//SKILL.md` identical. Diagnostic workflows + use read-only SnapshotDB operations; setup and collection have separate + mutation/consent boundaries. +7. **Evidence and localization.** Snapshot `PROVENANCE.md` is append-only; + changes anywhere under `snapshot/` require the PR provenance decision, + including documentation-only changes. Executable fixture review is a + separate [acceptance process](tests/fixtures/AGENTS.md). Keep English/Chinese + user guides behaviorally aligned when public behavior changes. ## Change Routing -| Change | Start here | Focused tests | +| Change | Start with | Verification owner | | --- | --- | --- | -| CLI options or terminal rendering | `src/pt_snap_cli/cli.py`, `cli_reports.py`, `cli_skills.py`, `cli_output.py`, and the owning core service | `tests/test_cli.py`, `tests/test_cli_json.py`, `tests/test_completion.py` | -| Focus precedence or persistence | `src/pt_snap_cli/config.py`, `src/pt_snap_cli/core/focus_service.py`, `src/pt_snap_cli/context.py` | `tests/test_config.py`, `tests/test_context.py`, `tests/core/test_focus_service.py` | -| Context/executor caching | `src/pt_snap_cli/core/context_cache.py`, `src/pt_snap_cli/api.py`, `src/pt_snap_cli/core/query_service.py` | `tests/core/test_context_cache.py`, `tests/test_snapshot_analyzer_cache.py`, `tests/test_query_cache_perf.py` | -| Query schema, SQL, or categories | `src/pt_snap_cli/query/`, `src/pt_snap_cli/core/query_service.py` | `tests/query/`, `tests/core/test_query_service.py` | -| Python API behavior | `src/pt_snap_cli/api.py` | `tests/test_api.py`, `tests/test_contract_cli_api.py` | -| Snapshot import or metadata | `src/pt_snap_cli/core/import_service.py`, `src/pt_snap_cli/core/import_metadata.py`, `src/pt_snap_cli/core/snapshot_import_backend.py` | `tests/core/test_import_*.py`, `tests/test_snapshot_db.py` | -| Snapshot splitting or replay | `src/pt_snap_cli/core/split_service.py`, `src/pt_snap_cli/snapshot/` | `tests/core/test_split_service.py`, `tests/snapshot/` | -| Reports | `src/pt_snap_cli/core/report_service.py`, `src/pt_snap_cli/cli_reports.py` | `tests/core/test_report_service.py`, report cases in `tests/test_cli.py` | -| Skill list/install destinations or catalog packaging | `src/pt_snap_cli/core/skill_service.py`, `src/pt_snap_cli/bundled_skills/`, `src/pt_snap_cli/cli_skills.py` | `tests/core/test_skill_service.py`, `tests/test_bundled_skills.py`, skill cases in `tests/test_cli.py` | -| Agent setup, Ascend NPU collection, diagnostics, or skill evaluation | `skills/`, `tests/skills/`, and the referenced CLI/query surfaces | `tests/skills/` | -| Packaging or release | `pyproject.toml`, `.github/workflows/` | `tests/test_package.py`, `tests/test_release_workflow.py` | -| Executable fixtures | `tests/fixtures/snapshots/` | `tests/test_fixture_provenance.py` before any deserializing suite | - -## Documentation Boundaries - -- `README.md` and `README_zh.md` are user-facing entry points. -- `docs/en/` and `docs/zh/` must remain behaviorally aligned for user guides. -- Keep agent instructions in this file unless a subtree gains an independent - lifecycle or maintenance contract that warrants a local `AGENTS.md`. +| CLI/API, completion, focus, Context | [Package adapters](src/pt_snap_cli/AGENTS.md) | [Cross-surface tests](tests/AGENTS.md) | +| Cache, import/split, reports, skill destinations | [Core services](src/pt_snap_cli/core/AGENTS.md) | [Service tests](tests/core/AGENTS.md) | +| SQL, parameters, completeness, result semantics | [Query engine](src/pt_snap_cli/query/AGENTS.md), [YAML templates](src/pt_snap_cli/query/templates/AGENTS.md) | [Query tests](tests/query/AGENTS.md) | +| Representation, replay, schema, slicing | [Snapshot runtime](src/pt_snap_cli/snapshot/AGENTS.md) | [Runtime tests](tests/snapshot/AGENTS.md) | +| Diagnostic instructions and evaluation | [Skills](skills/AGENTS.md) | [Skill contracts/harness](tests/skills/AGENTS.md) | +| Packaging or release | [Source layout](src/AGENTS.md), [workflows](.github/workflows/AGENTS.md) | `tests/test_package.py`, `tests/test_release_workflow.py` | diff --git a/benchmarks/AGENTS.md b/benchmarks/AGENTS.md index b87f273..4970337 100644 --- a/benchmarks/AGENTS.md +++ b/benchmarks/AGENTS.md @@ -1,26 +1,36 @@ - +# Opt-In Performance Measurements -# benchmarks +Parent scope: [repository](../AGENTS.md). -## Purpose -`benchmarks` contains opt-in performance measurements. These scripts are not -pytest entry points: they can consume substantial CPU, memory, and time, and the -import benchmark deserializes reviewed executable fixtures. +These are standalone scripts, not pytest targets. They can consume substantial +CPU/memory/time; the import benchmark deserializes reviewed executable fixtures. -## Entry Points -| File | Behavior | +| Script | Inputs and side effects | | --- | --- | -| `baseline_import.py` | Runs warmup/formal imports in temporary directories, profiles one import, and prints timing, RSS, database, and correctness summaries. | -| `sqlite_write_throughput.py` | Compares default and optimized SQLite writers using temporary databases. | - -## Safety And Execution -- Run from the repository root with `PYTHONPATH=src python benchmarks/