agentic-preflight 0.3.0__tar.gz

agentic_preflight-0.3.0/.gitignore

@@ -0,0 +1,219 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+.DS_Store

agentic_preflight-0.3.0/CHANGELOG.md

@@ -0,0 +1,230 @@
+# Changelog
+
+All notable changes to Agentic Preflight are documented here. This project follows
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+## [0.3.0] - 2026-08-12
+
+### Added
+
+- Supply-chain maintenance and verification: Dependabot updates Python and GitHub
+  Actions dependencies, locked runtime dependencies are audited for published
+  vulnerabilities, CodeQL performs Python static analysis, and release artifacts ship
+  with a CycloneDX SBOM plus signed build-provenance and SBOM attestations.
+- A compatibility policy and Monday/Thursday regression coverage for the oldest
+  supported boundary, macOS 15 with Python 3.11. Pull-request CI remains the fast
+  Ubuntu/Python 3.13 combination, while manual and release runs retain the broad
+  six-way matrix.
+
+- Configurable, attestable review independence. `[review] executor = "command"` runs an
+  external reviewer over the same complete bundle returned by `context`, while
+  `require_command_for` can require that executor for selected risk levels. Command
+  failures have bounded, restart-safe retries, and attestation schema v3 records the
+  executor plus redacted command evidence.
+
+- Snapshot-bound review coverage. `context` inventories every changed hunk plus
+  non-textual file changes; review submissions must assert examination of that exact
+  manifest, findings cite units, and code derives a complete cited/clean receipt.
+  Any repair commit invalidates coverage and reopens review before validation continues.
+
+- Conservative rebase tolerance for in-place runs. `start` preserves a prior green
+  attestation only when the rewritten commit has an identical complete tree, effective
+  configuration, and clean Git merge result against the freshly synchronized base.
+- Managed Agent Skill integrations for Cursor, opencode, and Amp, alongside Codex and
+  Claude Code.
+
+- An idempotent `install.sh` for installing or updating the CLI and all managed agent
+  skill copies directly from a source checkout.
+- A conservative `uninstall.sh` that pauses for per-repository
+  `agentic-preflight:uninstall` cleanup before removing managed user-scoped skills and
+  the CLI. Project cleanup removes configuration and managed hook logic while preserving
+  unrelated hooks, run history, and attestations.
+- `[pr] mode = "auto" | "manual"`, defaulting to automatic pull-request creation after
+  the user approves the push gate. Manual PR mode leaves creation to the user and reports
+  a compare URL instead.
+- `[approval] mode = "manual_merge" | "environment" | "peer_review"` for high-risk
+  pull requests. Manual merge is the default, Environment mode uses a configurable
+  GitHub Environment, and peer review retains the exact-head eligible-reviewer policy.
+  The trusted check rejects GitHub auto-merge while manual-merge mode is active.
+- Deterministic path-based risk classification with separate low, medium, and high
+  levels. High risk invokes the configured merge-approval mode, while publication still
+  uses the normal confirmation-token gate. Risk remains separate from the diff byte
+  budget.
+- A pull-request attestation job that runs the verifier from the protected base commit
+  and fetches attestations from same-repository branches or public forks. Governance
+  surfaces now have a checked-in CODEOWNERS policy.
+- A trusted high-risk approval check that dispatches manual-merge, Environment, and peer
+  review modes. Peer review rejects bot, unaffiliated, self, stale-head, dismissed, and
+  superseded approvals.
+- Green records are now portable Git-note attestations in
+  `refs/notes/agentic-preflight`. Lint and test evidence includes the exact command,
+  exit code, and SHA-256 of redacted captured output, and the normal push path sends
+  the branch and attestation ref atomically.
+- `agentic-preflight verify <sha>` provides a fail-closed CI check for the note's
+  schema, exact commit/tree binding, complete stages, and shell-stage evidence.
+
+### Changed
+
+- CI and release workflows now use `actions/checkout` 7.0.1,
+  `actions/upload-artifact` 7.0.1, `actions/download-artifact` 8.0.1, and
+  `pypa/gh-action-pypi-publish` 1.14.2. Development dependency floors now require
+  Hypothesis 6.165.2 and Ruff 0.16.2, with the lockfile updated accordingly.
+
+- Dependabot version updates are grouped into one weekly Python dependency pull
+  request and one weekly GitHub Actions pull request, reducing preflight review and
+  attestation overhead without exempting bot-authored commits from the gate. The
+  attestation and CI guide documents how to attest the exact bot-authored commit and
+  re-run its hosted checks.
+
+- The README now matches the 0.3.0 release surface, uses release-stable links when
+  rendered on PyPI, and keeps only the quickstart and core safety contract. Detailed
+  hook behavior, portable attestations and CI, configuration, and extended limitations
+  live in focused linked guides that are included in the source distribution.
+- An explicit request to push, publish, or create/open a pull request now authorizes the
+  matching post-verification push. The gate still displays the exact remote, branch,
+  commits, and risk summary, but no longer forces a duplicate confirmation unless that
+  summary differs materially from what the user authorized.
+- Code-owned mechanical findings now block regardless of reviewer severity policy, so
+  `[docs] require_changelog = true` cannot be silently weakened by excluding `high`
+  from `[docs] blocking_severities`.
+- Local validation now runs review → docs → lint → test, leaving the potentially
+  expensive test command until all review, documentation, and mechanical lint repairs
+  are committed. A lint-only repair therefore cannot force an otherwise unnecessary
+  second test run; committed test repairs still invalidate docs and lint before retry.
+- Pull requests and pushes to `main` now run one test combination, `ubuntu-latest` on
+  Python 3.13, rather than the full six-way matrix. The matrix of Ubuntu and macOS
+  against Python 3.11, 3.12, and 3.13 still runs on release tags, where it now gates
+  the PyPI upload, and on demand by running the CI workflow manually from the Actions
+  tab. Supported platforms and Python versions are unchanged; only the point at which
+  every combination is exercised has moved.
+- The test matrix now lives in a single reusable workflow that both the CI and release
+  workflows call, rather than being copied into each. Contributors will see the test
+  checks reported under a nested name, `test / test (ubuntu-latest, py3.13)`.
+- The packaged description now states what the tool does rather than what it omits. The
+  previous summary led with "Calls no LLM, ever", which is true of this package and
+  misleading about a run, in which every judgment is produced by a model. PyPI renders
+  that field as the project summary with none of the surrounding explanation, so it has
+  to stand on its own. The README intro keeps the underlying point in the form that
+  survives being read alone: no API key and no second model.
+- The README now leads with what the tool does and defers the detail to linked pages.
+  Reference material that a first-time reader does not need moved into `docs/`:
+  `installation.md`, `change-scope.md`, `worktree-modes.md`, `configuration.md`, and
+  `limits.md`. The prior-art comparison moved below the technical sections, since it
+  answers a question a reader has not yet asked. No documented behaviour changed, and
+  the configuration example stays in the README, where the test suite requires every
+  config section to appear.
+- The `[diff] exclude` example now says that setting the key replaces the eight built-in
+  globs rather than extending them. The example lists four of the eight, so copying it
+  verbatim silently dropped `**/*.min.css`, `**/__snapshots__/**`, `**/*.pb.go`, and
+  `**/*_pb2.py`. The full default list is now in `docs/configuration.md`.
+- The README now opens with a recorded demonstration of a run: a push blocked by the
+  pre-push hook, a review that catches an unguarded division by zero, the fix verified,
+  and the gate stopping to ask before pushing. The recording is real CLI output, and the
+  VHS tape that produces it is committed as `docs/demo.tape`, alongside
+  `docs/demo-fixture.sh`, which builds the throwaway repository the tape records
+  against. `./docs/demo-fixture.sh && vhs docs/demo.tape` regenerates the recording from
+  nothing, so the demonstration of a tool that verifies claims can itself be verified
+  rather than taken on trust.
+
+### Removed
+
+- The `ap` console-script alias. The supported executable is `agentic-preflight`.
+- Built-in GitHub pull-request creation, CI monitoring, and destructive post-merge
+  cleanup. The skill now hands these host-level tasks to `gh`; the core retains the
+  quality gate, atomic branch-and-attestation push, `finish`, and `gc`.
+- The `pr`, `ci`, and `cleanup` commands and their `[publish]` and `[ci]`
+  configuration sections.
+- `docs/plans/` and the design document it held. It described the architecture as it was
+  being decided rather than as it now is, and the parts still worth reading have since
+  been said in the README and the `docs/` pages. It remains in git history.
+
+### Fixed
+
+- Cross-stage lint/test repair cycles preserve each stage's failed-attempt counter, so
+  alternating repairs cannot reset and evade the configured `max_attempts` stop.
+- Attestation reuse now names both mandatory terminal outcomes: lint must be green and
+  test must be green or explicitly skipped.
+
+- Synchronizing attestations now preserves locally-ahead and disjoint remote note
+  histories. A valid local attestation no longer makes the next preflight start fail
+  with a non-fast-forward fetch; conflicting notes for the same commit still fail loud.
+- Manual CI runs are no longer cancelled by other CI activity. Every run on a ref
+  shared one concurrency group with `cancel-in-progress`, so a manual run of the full
+  matrix could be superseded by a push to `main` or by a second manual run. That is
+  the run the release process uses to check macOS and Python 3.11 and 3.12 before a
+  tag exists, and a cancelled run reports neither pass nor fail. Manual runs now get
+  a group of their own; pushes and pull requests still supersede older runs on the
+  same ref.
+
+## [0.2.1] - 2026-07-28
+
+First release published to PyPI.
+
+### Added
+
+- Tag-triggered release workflow that publishes to PyPI using Trusted Publishing, so
+  no long-lived API token is stored in the repository or in GitHub secrets. The upload
+  is bound to a `pypi` GitHub Environment and waits for reviewer approval, and the
+  build refuses to proceed when the pushed tag does not match the project version.
+- `docs/RELEASING.md`, covering the one-time PyPI publisher registration, the GitHub
+  environment setup, and the per-release checklist.
+- Community health files: `CONTRIBUTING.md`, `SECURITY.md`, `SUPPORT.md`, issue
+  templates, and a pull request template.
+- Inline type information: the package now ships `py.typed`, so type checkers read its
+  annotations directly.
+- A coverage badge produced and published by CI without a third-party service, and a
+  prior art section in the README.
+
+### Changed
+
+- Documentation-only and CI-configuration-only changes now record the software test
+  stage as explicitly skipped instead of requiring a test command to run.
+- The skill now instructs a `git pull --ff-only` on the base branch after a confirmed
+  cleanup, so the source checkout matches the merged result.
+- Attribution moved from the top of the README to a Credits section beside the license,
+  and the package author is now the GitHub handle rather than a legal name.
+
+### Fixed
+
+- Skipped GitHub checks are no longer treated as failures. A pull request whose
+  workflow correctly skips a job was previously reported as a CI failure.
+- The source distribution is now built from an explicit allowlist. It previously
+  included everything not matched by the root `.gitignore`, which made the published
+  artifact depend on the contents of the local working tree and could fail the build
+  outright when a stray virtual environment was present.
+
+## [0.2.0] - 2026-07-23
+
+First tagged pre-release.
+
+### Added
+
+- Deterministic review, test, documentation, lint, merge-back, and push workflow.
+- Advisory pre-push hook keyed to the exact verified commit.
+- Manual gate mode for workflows where only a person may perform the final push.
+- Codex and Claude Code skill installation.
+- In-place, reusable, and strict validation checkout modes.
+- GitHub pull request publishing and CI monitoring through the `gh` CLI.
+- Explicit CI coverage for Python 3.11 through 3.13 on macOS and Linux.
+
+### Changed
+
+- Renamed every pre-release product surface from `agentic-cli` to
+  `agentic-preflight`, including the Python package, executable, skill, configuration,
+  state directories, and internal validation branch prefix.
+- Reframed the product as an advisory guard against accidental unverified pushes.
+- Added a 60-second README walkthrough with command output captured from a local demo.
+
+### Supported platforms
+
+- macOS
+- Linux
+
+Windows is not supported because the implementation requires `fcntl`, Bash, and POSIX
+process groups.
+
+[0.3.0]: https://github.com/elanthus/agentic-preflight/releases/tag/v0.3.0
+[0.2.1]: https://github.com/elanthus/agentic-preflight/releases/tag/v0.2.1
+[0.2.0]: https://github.com/elanthus/agentic-preflight/releases/tag/v0.2.0

agentic_preflight-0.3.0/COMPATIBILITY.md

@@ -0,0 +1,35 @@
+# Compatibility policy
+
+Agentic Preflight supports Python 3.11, 3.12, and 3.13 on macOS 15 or newer and on
+Linux. Windows is not supported because the implementation requires Bash, `fcntl`, and
+other POSIX behavior. Git 2.30 or newer is required.
+
+## Validation tiers
+
+The supported combinations receive different validation frequencies so pull-request
+feedback stays fast:
+
+- Pull requests and pushes to `main` run on `ubuntu-latest` with Python 3.13.
+- A scheduled regression run covers the oldest supported boundary, macOS 15 with
+  Python 3.11, every Monday and Thursday.
+- Manual CI runs and release tags cover Python 3.11, 3.12, and 3.13 on both
+  `ubuntu-latest` and `macos-latest`.
+
+A platform is supported even when it is not in the pull-request job. A failure that is
+specific to a supported combination is a release blocker and should be fixed with the
+same priority as a pull-request CI failure.
+
+Other POSIX systems and newer Python prereleases may work, but they are best effort
+until they are added to the supported matrix. Successful installation on a version
+outside the matrix does not make that version supported.
+
+## Compatibility changes
+
+The command-line interface, configuration file, attestation schema, and documented
+Python API follow Semantic Versioning. During the current `0.x` series, incompatible
+changes may ship in a minor release and will be called out in `CHANGELOG.md`.
+
+Removing a Python or operating-system version should be announced in the changelog at
+least one minor release in advance when practical. An upstream end-of-life or hosted
+runner retirement may require a faster change; in that case the release notes must
+identify the constraint and the last compatible Agentic Preflight release.

agentic_preflight-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,48 @@
+# Contributing
+
+Thanks for helping improve Agentic Preflight. Bug reports, focused feature proposals,
+documentation fixes, and code contributions are welcome.
+
+## Before opening a change
+
+- Search existing issues and pull requests to avoid duplicate work.
+- Open an issue before a large behavioral change so the approach can be agreed first.
+- Report vulnerabilities privately as described in [SECURITY.md](SECURITY.md), not in
+  a public issue.
+
+## Development setup
+
+Agentic Preflight supports the Python and operating-system combinations listed in
+[COMPATIBILITY.md](COMPATIBILITY.md), Git 2.30 or newer, and `uv`.
+
+```bash
+git clone https://github.com/elanthus/agentic-preflight.git
+cd agentic-preflight
+uv sync --group dev
+```
+
+Run the same core checks used by CI:
+
+```bash
+uv run ruff check agentic_preflight tests
+uv run mypy agentic_preflight
+uv run pytest --cov=agentic_preflight --cov-report=term-missing
+```
+
+The test suite uses temporary real Git repositories. Tests that exercise pushes and
+worktrees can take longer than ordinary unit tests and require a working Git binary.
+
+## Pull requests
+
+Keep changes focused and include tests for observable behavior. Update user-facing
+documentation whenever a reader following the current instructions would otherwise be
+wrong. In the pull request, explain the problem, the chosen approach, and the checks
+you ran. All CI checks, including the 85% coverage floor and built-wheel smoke test,
+must pass before merge.
+
+Pull-request CI intentionally uses only Ubuntu and Python 3.13. The oldest supported
+macOS/Python boundary runs every Monday and Thursday, and the broad six-way matrix runs
+manually and on release tags; see [COMPATIBILITY.md](COMPATIBILITY.md).
+
+By submitting a contribution, you agree that it is licensed under the repository's
+Apache License 2.0.