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
90 changes: 44 additions & 46 deletions .github/AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,46 +1,44 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-05-26 | Updated: 2026-08-08 -->

# .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.

<!-- MANUAL: Any manually added notes below this line are preserved on regeneration -->
# 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.
65 changes: 21 additions & 44 deletions .github/ISSUE_TEMPLATE/AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,44 +1,21 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-05-26 | Updated: 2026-08-09 -->

# 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.

<!-- MANUAL: Any manually added notes below this line are preserved on regeneration -->
# 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.
73 changes: 37 additions & 36 deletions .github/workflows/AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,48 +1,49 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-05-26 | Updated: 2026-08-08 -->
# 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

<!-- MANUAL: Any manually added notes below this line are preserved on regeneration -->
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.
Loading
Loading