pyahead 0.2.1__tar.gz

pyahead-0.2.1/.gitignore

@@ -0,0 +1,18 @@
+.coverage
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+__pycache__/
+build/
+dist/
+*.egg-info/
+benchmark-results.json
+
+# PyPI validation harness (docs/pypi-validation.md): acquired manifest,
+# wheelhouse, and work directory are local acquisition metadata, never committed.
+/work/pypi-manifest.json
+/work/pypi-wheelhouse/
+/work/pypi-validate/
+/work/pypi-report.json
+/work/pypi-disagreements.csv

pyahead-0.2.1/AGENTS.md

@@ -0,0 +1,38 @@
+# Codex working agreement
+
+`docs/design.md` is the implementation contract. Read it completely with
+`README.md`, `pyproject.toml`, and current repository instructions before work.
+
+- Implement only the requested milestone. Never add later-milestone analyser,
+  registry, Django, hosted-service, or other features opportunistically.
+- Preserve public contracts and unrelated work. Record a justified design
+  difference in `docs/design.md` in the same change.
+- Keep Python in `src/pyahead`, require Python 3.11+, and add only dependencies
+  used by the current milestone.
+- One passing milestone gets one intentional commit; never combine milestones.
+
+Treat `docs/design.md`, `AGENTS.md`, and `.github/workflows` as protected: change
+them only when the requested milestone explicitly requires it. The `tool.ruff`,
+`tool.mypy`, `tool.pytest.ini_options`, `tool.coverage.run`, and
+`tool.coverage.report` tables in `pyproject.toml` are quality policy; never
+weaken a threshold to make a change pass.
+
+Stop at Gate C before M7-M8; Gate C needs recorded corpus-precision evidence and
+accountable human approval, and no agent may approve its own precision evidence.
+Refuse M9 here — the hosted service belongs in a separate private repository —
+and refuse M10 until `docs/c-api-design.md` exists.
+
+```console
+uv sync --frozen
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy src scripts
+uv run pytest
+uv build
+uv run pyahead --version
+git diff --check
+```
+
+Run milestone-specific checks too. Inspect the final diff for generated files,
+secrets, absolute paths, weakened policy, unsafe subprocess/Git behaviour, and
+unrelated changes.

pyahead-0.2.1/CHANGELOG.md

@@ -0,0 +1,137 @@
+# Changelog
+
+All notable user-visible changes are recorded here. PyAhead follows Semantic
+Versioning, including prerelease identifiers while public contracts are still
+stabilizing.
+
+## Unreleased
+
+## 0.2.1 - 2026-09-13
+
+Precision fixes found by adjudicating the PyPI top-1000 against real
+interpreters. No public contract changes.
+
+### Fixed
+
+- `sys.version_info[0]` compared against an integer, the Python 2/3 split
+  such as `if sys.version_info[0] < 3:`, is now evaluated as a version guard,
+  so a Python-2-only branch no longer produces findings for Python 3 targets.
+- The annotation of a local variable inside a function body, which Python
+  never evaluates or stores, is now a typing-only reference, so runtime-only
+  rules no longer report it. Parameter, return, class-body and module-level
+  annotations are unchanged, including under
+  `from __future__ import annotations`, because runtime introspection such
+  as `typing.get_type_hints` still evaluates them. Both fixes come from the
+  runtime adjudication of the PyPI top-1000 recorded in
+  `docs/evidence/pypi-top-1000.md`.
+
+## 0.2.0 - 2026-09-01
+
+First public-alpha release. It carries the evidence providers that
+`docs/design.md` §4.3 assigns to `0.2`: opt-in pytest deprecation-warning
+evidence and opt-in dependency metadata and resolver evidence. No `0.1.0`
+release was published; the `0.1.0a2` candidate is superseded by this version.
+
+### Added
+
+- A closed static-report JSON Schema, packaged schema resource, `py.typed`
+  marker, and documented narrow public Python API with installed-wheel strict
+  mypy verification.
+- Opt-in dependency compatibility reports with declared environment targets,
+  separate application and library semantics, direct build-free wheel/sdist
+  metadata inspection, target marker evaluation, `Requires-Python` and wheel
+  availability distinctions, and an isolated `uv` adapter with explicit
+  offline, network, index, and timeout controls. Wheel structure, direct URL,
+  coherent-target, and complete transitive-dependency evidence fail closed;
+  closed-wheelhouse artifact absence remains distinct from proven constraint
+  conflicts and operational index failures. Direct application and library
+  samples retain precise artifact availability but remain incomplete
+  compatibility evidence until resolution closes the inventory, except that an
+  exact, final `Requires-Python` exclusion remains declared incompatible;
+  resolver-selected extras require exact `Provides-Extra` provenance. Nested
+  dependency extras reach a fixed point, and
+  archive member, shared expanded-data, and decoder limits are enforced before
+  unbounded object creation, decompression, or LZMA dictionary allocation.
+  Dependency evaluation and correlation share a bounded work budget, and public
+  metadata records must preserve exact container identity. Target-selected
+  metadata now exclusively supplies extras and dependency edges; conflicting
+  artifact declarations, ambiguous local-version pins, unreachable resolver
+  packages, legacy source-metadata dynamism, malformed markers, impossible
+  target versions, resolver output, aggregate metadata, and sdist identity
+  boundaries fail closed as invalid input or explicit incomplete evidence, as
+  appropriate.
+- Versioned pytest deprecation-warning evidence, explicit user-CI collection,
+  commit-aware ingestion, subject/timeline-aware static/observed relationships,
+  explicit per-artifact and aggregate resource limits, indexed relationship
+  processing, bounded collection-time warning retention, incremental artifact
+  sizing, and visible unmatched, conflicting, or stale observations in text and
+  JSON reports.
+- Deterministic repository discovery, Python-version reachability, strict
+  configuration, baselines, rule-specific suppressions, JSON, and SARIF 2.1.0.
+- A source-linked CPython registry with explicit coverage manifests and
+  positive and negative fixtures for implemented rules.
+- A Linux, macOS, and Windows CI matrix for Python 3.11 through 3.14, plus an
+  advisory Python 3.15 prerelease job.
+- Isolated wheel and sdist install-and-scan smoke tests.
+- Checked performance budgets and a synthetic benchmark command.
+- A privacy-minimal 100-repository corpus runner and deterministic
+  high-confidence false-positive review worksheet.
+- Complete user, release, security, privacy, and corpus-review documentation.
+- The first end-to-end static-analysis slice, including exact module imports,
+  deterministic text and JSON findings, bounded discovery, and stable exits.
+- Initial package, command-line entry point, locked development environment,
+  quality policy, build configuration, and CI.
+
+### Changed
+
+- The package maturity classifier is now Alpha.
+- Gate C now uses accountable review of reproducible public-corpus precision
+  evidence; continuous-use adoption is measured after public distribution.
+- Exact `sys.path` mutation ambiguity and removal-safe `hasattr` short circuits
+  no longer produce high-confidence post-removal blockers.
+- Corpus scan and read-only Git verification subprocesses have separate,
+  configurable finite timeouts.
+- Release install smoke tests now use one explicit run-local child environment,
+  resolve online only from public PyPI, and exercise wheel and sdist installation
+  from an explicit operator-selected uv cache on every supported hosted
+  operating system. CI creates a fresh cache, populates it through the online
+  public-PyPI smokes, and then reuses it for offline evidence.
+
+### Removed
+
+- The milestone controller and its development automation: `scripts/autopilot.py`,
+  `automation/`, `docs/autopilot.md`, and the offline controller test suite. The
+  source distribution no longer ships the `automation/` tree. Milestone rules,
+  protected paths, quality-policy tables, and the Gate C approval requirement are
+  retained as prose in `AGENTS.md` and `docs/design.md`.
+
+### Fixed
+
+- Root-bounded Windows input now reports absent, access-denied, and
+  non-directory paths as the corresponding standard `FileNotFoundError`,
+  `PermissionError`, and `NotADirectoryError`, instead of a generic NTSTATUS
+  `OSError`. Optional configuration, baselines, and evidence are no longer
+  misreported as unreadable when they are simply absent.
+
+### Security
+
+- Documented offline scan, no-telemetry, no-target-execution, filesystem, and
+  corpus-data boundaries.
+- Human-readable reports, CLI diagnostics, registry and dependency presentation,
+  and project maintenance logs now escape untrusted terminal controls, embedded
+  line breaks, and dangerous Unicode separators while preserving printable
+  Unicode and deterministic machine formats.
+- Root-bounded Windows output creation and replacement stays anchored to opened
+  non-reparse directory handles and fails closed if those APIs are unavailable.
+- Corpus review worksheets carry and verify the exact result digest so a
+  partially published pair cannot be mistaken for matching Gate C evidence.
+- Corpus review worksheets quote repository-derived `path`, `subject`, and
+  `match_kind` values so a scanned file name cannot become a live formula in a
+  reviewer's spreadsheet, and reject an unescaped one when a reviewed worksheet
+  is read back. Reviewer prose columns stay free text.
+- Release smoke children no longer inherit ambient installer configuration,
+  caches, proxies, Python environments, or credentials, and retained failure
+  diagnostics redact common credential forms before truncation.
+
+Release headings, dates, and comparison links are added only after their
+immutable tags exist.

pyahead-0.2.1/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

pyahead-0.2.1/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.5
+Name: pyahead
+Version: 0.2.1
+Summary: Evidence-backed Python compatibility forecasting
+Project-URL: Documentation, https://github.com/diegorusso/pyahead/blob/main/docs/usage.md
+Project-URL: Issues, https://github.com/diegorusso/pyahead/issues
+Project-URL: Repository, https://github.com/diegorusso/pyahead
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Requires-Dist: libcst<2,>=1.8
+Requires-Dist: packaging<27,>=26.2
+Requires-Dist: pathspec<2,>=1.1
+Requires-Dist: pyyaml<7,>=6.0.2
+Description-Content-Type: text/markdown
+
+# PyAhead
+
+PyAhead is an evidence-backed Python compatibility forecaster. It scans a
+repository without importing or executing its code, then presents one timeline
+for each known CPython deprecation, removal, call change, or behavior change that
+matches the source.
+
+## Limitations — read before use
+
+PyAhead is a public alpha. A clean scan is **not proof of compatibility**. The
+bundled registry covers reviewed, statically representable Python-level entries
+from selected CPython sources; it does not cover arbitrary runtime behavior,
+dependencies, C extensions, reflection, generated code, or every Python API.
+Run the repository's tests on every supported target interpreter as well.
+
+The default static command does not execute target code, install target
+dependencies, infer general receiver types, resolve arbitrary dynamic imports,
+access the network, or send telemetry. Dependency evidence is a separate opt-in
+command with explicit targets, network policy, and deadlines. Version helpers,
+user-defined constants, patch-level guards, and general control flow outside
+the documented lexical grammar remain unknown.
+Skipped, unreadable, oversized, unparseable, or over-limit source entries make
+analysis incomplete rather than silently clean. See
+[all documented limitations](docs/usage.md#limitations).
+
+## Status
+
+Version `0.2.1` is the first published public-alpha release. It provides deterministic
+text, JSON, and SARIF 2.1.0 reports; strict project configuration; baselines and
+rule-specific suppressions; version-guard and typing-context reachability; a
+source-linked, coverage-audited CPython registry; opt-in pytest warning
+evidence; and opt-in dependency metadata and isolated-resolution evidence.
+
+PyAhead supports host Python 3.11 through 3.14 on Linux, macOS, and Windows.
+The host interpreter is independent of the baseline and horizon Python versions
+being assessed. Python 3.15 prerelease CI is advisory until support is claimed.
+
+The first opt-in dynamic provider collects deprecation warnings with an explicit
+pytest plugin in the repository owner's CI, then merges its versioned artifact
+with `pyahead check --evidence`. Observed warnings stay separate from static
+inference; unmatched and different-commit evidence remains visible. PyAhead
+does not run those tests in a hosted scanner.
+
+`pyahead dependencies` separately inspects supplied wheel, source-distribution,
+or Core Metadata files without executing build backends. An optional isolated
+`uv` adapter has explicit offline/online and timeout controls. Dependency
+results distinguish exact declared incompatibility, independently corroborated
+constraint failures, closed-wheelhouse target-artifact absence, sample-level
+artifact availability, and incomplete evidence. Direct artifact samples remain
+compatibility unverified until a complete resolution closes the relevant
+inventory, except that an exact, final `Requires-Python` exclusion remains
+declared incompatible.
+
+Gate B is exercised by repository tests and clean wheel/sdist installation.
+Gate C requires evidence from 100 active public repositories, at least 95%
+sampled precision for high-confidence findings, false-positive regressions,
+retained limitations, and accountable product-owner approval. Continuous-use
+adoption is measured after the alpha is publicly available; it is not a
+prerequisite for the M7–M8 dynamic-evidence work.
+
+## Install
+
+After the alpha is published, install it in an isolated tool environment:
+
+```console
+pipx install pyahead==0.2.1
+# or run without a persistent tool environment
+uvx pyahead==0.2.1 --version
+```
+
+Before publication, build and install the candidate from this repository:
+
+```console
+uv build
+pipx install dist/pyahead-0.2.1-py3-none-any.whl
+```
+
+Installing PyAhead may contact the configured package index to obtain PyAhead
+and its dependencies. Running `pyahead check` itself is offline.
+
+## Quick start
+
+Scan a repository with an explicit inclusive policy:
+
+```console
+pyahead check . --baseline-python 3.11 --horizon-python 3.14
+```
+
+Or declare strict configuration in `pyproject.toml`:
+
+```toml
+[tool.pyahead]
+baseline-python = "3.11"
+horizon-python = "3.14"
+include = ["src/**/*.py", "tests/**/*.py"]
+exclude = ["src/generated/**"]
+source-roots = ["src"]
+minimum-confidence = "high"
+fail-on = "breaking"
+respect-gitignore = true
+show-unscheduled = true
+```
+
+Then run:
+
+```console
+pyahead check
+```
+
+When the baseline is omitted, PyAhead can infer the lowest supported registry
+minor from `[project].requires-python` and records that provenance in the
+report. It never infers the baseline from the host interpreter.
+
+Exit code 1 means an unsuppressed finding met the selected `fail-on` gate; 2
+means invalid command, configuration, or registry input; 3 means analysis was
+incomplete; and 4 means an unexpected internal failure. Exit 0 means only that
+the configured static scan completed without a gated finding.
+
+## CI and review workflows
+
+Write SARIF or deterministic JSON atomically:
+
+```console
+pyahead check --format sarif --output pyahead.sarif
+pyahead check --format json --output pyahead.json --fail-on never
+```
+
+Adopt existing findings without hiding them from reports:
+
+```console
+pyahead baseline create --output .pyahead-baseline.json
+pyahead check --baseline-file .pyahead-baseline.json --fail-new-only
+```
+
+Inline suppressions are rule-specific and stay auditable:
+
+```python
+import cgi  # pyahead: ignore[CPY0001] -- migration tracked in issue 42
+```
+
+Unknown rule IDs remain visible diagnostics. Report, baseline, and output paths
+must remain beneath the selected project root, including through symlinks.
+
+Inspect the bundled registry without scanning a repository:
+
+```console
+pyahead registry validate
+pyahead registry coverage
+pyahead registry list
+pyahead explain CPY0001
+```
+
+## Documentation
+
+- [User guide](docs/usage.md)
+- [Static report JSON Schema](docs/schema/report-v1.json)
+- [Registry authoring](docs/registry-authoring.md)
+- [Security and privacy](docs/security-and-privacy.md)
+- [Performance budgets](docs/usage.md#performance)
+- [100-repository corpus and false-positive review](docs/corpus-review.md)
+- [PyPI top-1000 precision validation](docs/pypi-validation.md)
+- [Release process](docs/releasing.md)
+- [Changelog](CHANGELOG.md)
+- [Product and technical design](docs/design.md)
+
+## Development
+
+PyAhead requires Python 3.11 or newer. The locked development environment uses
+[uv](https://docs.astral.sh/uv/):
+
+```console
+uv sync --frozen
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy src scripts
+uv run pytest
+uv build
+uv run pyahead --version
+uv run python scripts/install_smoke.py --dist-dir dist --kind wheel
+uv run python scripts/install_smoke.py --dist-dir dist --kind sdist
+uv run python scripts/benchmark.py --repeat 1 --output -
+git diff --check
+```
+
+Project-wide branch coverage is enforced at 90%. A focused pytest invocation
+may therefore fail only because it did not cover the whole package; use
+`--no-cov` for isolated iteration, then run the complete suite.
+
+Read [the contribution guide](docs/contributing.md) before proposing a change.
+
+## License
+
+PyAhead is licensed under the Apache License 2.0. See [LICENSE](LICENSE).