Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
4 changes: 2 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ that local environment is intentionally available.
| 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) | Installation approval and read-only memory-diagnostic boundaries |
| Agent skills | [skills/AGENTS.md](skills/AGENTS.md) | Environment setup and read-only memory-diagnostic workflows |

## Runtime Topology

Expand Down Expand Up @@ -112,7 +112,7 @@ templates under category subdirectories are included by
| 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`, report commands in `src/pt_snap_cli/cli.py` | `tests/core/test_report_service.py`, report cases in `tests/test_cli.py` |
| Agent setup or peak-memory diagnostic skills | `skills/` and the referenced CLI/query surfaces | `tests/test_setup_skill.py`, `tests/test_memory_peak_breakdown_skill.py` |
| Agent setup, peak breakdown or fragmentation skills | `skills/` and the referenced CLI/query surfaces | `tests/test_setup_skill.py`, `tests/test_memory_peak_breakdown_skill.py`, `tests/test_memory_fragmentation_skill.py` |
| 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 |

Expand Down
15 changes: 11 additions & 4 deletions skills/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,24 +3,31 @@
# skills

## Purpose
`skills` contains agent workflows shipped with the repository. The setup skill
has an independent side-effect boundary because it may install packages into the
user's active Python environment after explicit approval; diagnostic skills use
existing SnapshotDB data without writes.
`skills` contains agent workflows shipped with the repository. Setup owns the
only Python-environment mutation boundary; diagnostic skills consume installed
`pt-snap` surfaces and keep snapshot analysis read-only.

## Scope
| Path | Responsibility |
| --- | --- |
| `pt-snap-setup/SKILL.md` | Detect the active interpreter, verify CLI ownership, request install approval, and re-verify the same environment. |
| `pt-snap-memory-peak-breakdown/SKILL.md` | Explain active memory at active, allocated, or reserved peak events without leak, fragmentation, or OOM overclaims. |
| `pt-snap-memory-fragmentation/SKILL.md` | Diagnose allocator gaps, runtime segment retention/churn, and fragmentation-consistent pressure without persisting analysis state. |

## Invariants
- Preserve the selected `sys.executable` path for every Python and pip command; canonical paths are only for ownership comparison.
- Never assume Conda, switch environments, use plain `pip`, or install automatically.
- Keep `editable` and PyPI choices explicit, and obtain confirmation before every install attempt.
- Do not add setup steps that write reports or modify pt-snap focus/configuration.
- Keep memory diagnostics SnapshotDB-only and read-only; pass database/device explicitly and delegate missing tooling to `pt-snap-setup`.
- Diagnostic skills must not install packages, import pickle snapshots, persist
focus, or turn allocator gaps into definitive fragmentation claims.
- Prefer packaged query templates for diagnostics. Any raw SQLite fallback must
document why a template is insufficient and enforce read-only access.

## Focused Tests
- Run `pytest tests/test_setup_skill.py` after setup-skill changes. The current executable test covers active-interpreter path preservation; review the remaining approval and reporting instructions statically.
- Run `pytest tests/test_memory_peak_breakdown_skill.py` after peak-breakdown skill changes; it locks command/template references, range fallback, and attribution caveats.
- Run `pytest tests/test_memory_fragmentation_skill.py` after fragmentation-skill
changes; it checks current command/template references, read-only boundaries,
runtime segment coverage, and conservative classifications.
Loading
Loading