pkgwhy 1.0.0__tar.gz → 1.5.0__tar.gz

{pkgwhy-1.0.0 → pkgwhy-1.5.0}/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## 1.5.0 - 2026-06-30
+
+- Add `docs/commercial-agent-platform.md` to describe the future commercial and agent platform direction without implementing cloud services, billing, hosted review, API keys, or secrets.
+- Document the product habit around `pkgwhy precheck`, `pkgwhy pip install`, and `pkgwhy agent precheck`.
+- Document future tiers for the free local CLI, Pro local policy packs, team review dashboard, hosted package review cache, shared organization policy, and agent install gateway.
+- Add explicit hosted-review boundaries so the current local CLI does not imply active cloud review or definitive malware detection.
+- Add tests that keep the commercial platform design doc future-only and boundary-aware.
+- Harden precheck and pip-gate follow-up review items: direct-reference handling, hash-locked requirements parsing, PyPI specifier release selection, Python 3.11-compatible tar extraction, private pip decision log paths/permissions, and CI pyproject gate coverage.
+- Harden second-pass review items: sanitized artifact URLs, stable-release preference for PyPI specifiers, safer keep-artifact failure handling, advisory-mode CI audit behavior, quarantine CLI coverage, and stricter pip requirements snapshot boundaries.
+
+## 1.4.0 - 2026-06-30
+
+- Add local registry trust states: `trusted`, `reviewed`, `quarantined`, `blocked`, and `unknown`.
+- Add trust-state storage to registry index entries and include trust state in tool judgement JSON and human output.
+- Add `pkgwhy registry trust <tool>`, `pkgwhy registry review <tool>`, `pkgwhy registry quarantine <tool>`, `pkgwhy registry block <tool>`, and `pkgwhy registry blocked`.
+- Enforce registry trust state in the local runner policy: `quarantined` and `blocked` tools are refused before execution.
+- Keep newly published local tools at `unknown` trust until a human marks them.
+- Keep tool lock/verify and registry export/import deferred rather than inventing incomplete trust guarantees.
+
+## 1.3.0 - 2026-06-30
+
+- Add a reusable GitHub Actions package-gate template at `examples/github-actions/pkgwhy-package-gate.yml`.
+- Document CI advisory, strict, and agent modes in `docs/ci-templates.md`.
+- The CI template installs `pkgwhy`, runs requirements precheck, emits JSON and Markdown audit reports, optionally runs agent precheck, uploads reports, and fails only in strict or agent mode.
+- Keep CI package-gate usage local and secret-free by default; no cloud service, hosted review, billing, or credentials are required.
+- Add static validation tests for the CI template and documentation boundaries.
+
+## 1.2.0 - 2026-06-30
+
+- Add `pkgwhy pip install <package>` as a local pip install gate over `pkgwhy precheck`.
+- Add `pkgwhy pip install -r requirements.txt` for requirements-file gate checks before pip is invoked.
+- Add schema-versioned `pkgwhy.pip_install_gate.v1` JSON with precheck decision, gate exit code, pip invocation status, override status, warnings, reasons, and embedded precheck output.
+- Add `--policy strict`, `--dry-run`, `--override-review`, `--override-block`, and `--override-reason` for explicit install-gate workflows.
+- Add best-effort compact local pip gate decision logs that omit full precheck evidence.
+- Keep tests deterministic by using fake pip runners and dry-run paths; tests do not install arbitrary public packages.
+- Keep the pip gate conservative: pip is called only after precheck allows it or an explicit override is used, and unavailable or incomplete precheck evidence exits without invoking pip.
+
+## 1.1.0 - 2026-06-30
+
+- Add top-level `pkgwhy precheck` as a local pre-install package gate for humans, CI, and agents.
+- Add schema-versioned `pkgwhy.precheck.v1` JSON for single package requirements, including decision, risk, confidence, evidence summaries, vulnerability/provenance/typosquat/static summaries, and embedded package judgement.
+- Add schema-versioned `pkgwhy.precheck_batch.v1` JSON for `pkgwhy precheck -r requirements.txt` and `pkgwhy precheck pyproject.toml`.
+- Add explicit `--download-artifacts` support that queries PyPI, downloads one wheel or source artifact to a temporary review directory, verifies SHA-256 when PyPI metadata provides it, extracts safely, statically inspects files, and deletes temporary files unless `--keep-artifacts` is set.
+- Add optional `--pypi`, `--osv`, and local `--vulnerability-file` enrichment boundaries to precheck without enabling network by default.
+- Add `--enforce-exit-code` for gate usage while keeping default JSON and human precheck commands easy to inspect interactively.
+- Keep precheck static-first: it does not install, import, or execute inspected package code.
+
 ## 1.0.0 - 2026-06-30
 
 - Promote the `1.0.0rc1` release-candidate surface to the final 1.0.0 tracked codebase after local release-prep review.

{pkgwhy-1.0.0 → pkgwhy-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pkgwhy
-Version: 1.0.0
+Version: 1.5.0
 Summary: Offline-first Python package intelligence and supply-chain security decision support.
 Project-URL: Homepage, https://github.com/devlukeg/pkgwhy
 Project-URL: Repository, https://github.com/devlukeg/pkgwhy
@@ -42,11 +42,11 @@ Know why a package exists before you or your agent trusts it.
 
 ## Status
 
-`pkgwhy` 1.0.0 is a Python supply-chain security decision-support tool for developers and AI agents. It is useful for local package inspection, conservative static package review, agent-readable JSON, vulnerability and provenance foundations, policy checks, and the local private-registry and runner MVP.
+`pkgwhy` 1.5.0 is a Python supply-chain security decision-support tool and local pip/CI install gate for developers and AI agents. It is useful for local package inspection, conservative static package review, agent-readable JSON, vulnerability and provenance foundations, policy checks, artifact precheck, guarded pip installs, CI package-gate templates, local registry trust states, commercial/agent platform planning, and the local private-registry and runner MVP.
 
 It is not a production security scanner, not malware-detection certainty, and not a full sandbox. Results are evidence and signals for review, not proof that a package is safe or malicious.
 
-Current packaged version: `1.0.0`.
+Current packaged version: `1.5.0`.
 
 ## What Works Now
 
@@ -58,6 +58,13 @@ pkgwhy explain typer
 pkgwhy why typer
 pkgwhy inspect typer
 pkgwhy judge typer --json
+pkgwhy precheck typer --json
+pkgwhy precheck "typer==0.12.5" --json
+pkgwhy precheck -r requirements.txt --json
+pkgwhy precheck pyproject.toml --json
+pkgwhy precheck annotated-doc==0.0.4 --download-artifacts --json
+pkgwhy pip install typer --dry-run
+pkgwhy pip install -r requirements.txt --dry-run
 pkgwhy agent policy --json
 pkgwhy agent precheck typer --json
 pkgwhy risk typer
@@ -87,6 +94,13 @@ Implemented capabilities include:
 - Metadata-derived provenance/source-trust fields from installed metadata and optional PyPI JSON, with unsupported attestation and trusted-publishing checks marked as unknown or not implemented.
 - Conservative risk level, decision, warning, recommendation, evidence, confidence, risk model version, and rule-ID output.
 - Human `inspect`, `risk`, and `judge` reports that show compact rule-evidence summaries, while JSON reports include structured rule details.
+- Pre-install package precheck for package requirements, requirements files, and `pyproject.toml` dependencies.
+- Explicit artifact-download precheck that downloads a PyPI wheel or source artifact to a temporary review directory, verifies SHA-256 when available, extracts safely, statically inspects files, and deletes temporary files by default.
+- Optional gate exit codes via `pkgwhy precheck --enforce-exit-code`.
+- Guarded pip install flow via `pkgwhy pip install`, with precheck first, stable exit codes, explicit overrides, and compact local decision logs.
+- Reusable GitHub Actions package-gate template with advisory, strict, and agent modes.
+- Local registry trust states for private tools: `trusted`, `reviewed`, `quarantined`, `blocked`, and `unknown`.
+- Commercial and agent platform architecture documentation for future local policy packs, team review, hosted evidence cache, shared organization policy, and agent install gateway.
 - Stable JSON output for agent workflows.
 - Schema-versioned agent policy and package precheck output.
 - Conservative non-interactive agent defaults that block unknown or high-risk package use until a human reviews the evidence.
@@ -100,6 +114,9 @@ pkgwhy registry list
 pkgwhy registry add local-copy ~/.pkgwhy/registry
 pkgwhy registry use local
 pkgwhy publish ./my_tool.py
+pkgwhy registry trust local/my_tool
+pkgwhy registry quarantine local/my_tool
+pkgwhy registry blocked
 pkgwhy tool inspect local/my_tool
 pkgwhy tool judge local/my_tool --json
 pkgwhy run local/my_tool
@@ -121,6 +138,7 @@ Current runner policy is intentionally conservative:
 - Corrupt registry indexes fail closed for publish and tool-judgement paths.
 - Symlinks are not bundled, and stored registry paths must remain inside the registry root.
 - Bundle hash mismatch or a missing bundle blocks execution.
+- Quarantined or blocked registry trust states block execution.
 - `sandbox_only` and `block` tool judgements block execution.
 - Non-interactive execution is blocked unless both the judgement and manifest agent policy allow it.
 - Tools with declared dependencies are not run yet because dependency installation is not implemented.
@@ -134,11 +152,12 @@ These are roadmap items, not current features:
 
 - Complete vulnerability database coverage, transitive vulnerability analysis, or guaranteed advisory freshness.
 - Default online vulnerability lookup. Network access is only used when explicitly requested.
-- Cached PyPI/source lookup beyond the current OSV response cache.
+- Persistent cached PyPI/source lookup beyond the current OSV response cache.
 - Cloud/private remote registry backends.
 - `pull`, mirroring, and remote synchronization.
 - Tool dependency installation in the runner.
 - Tool bundle signing and signature verification.
+- Tool lock/verify commands and registry export/import.
 - Dynamic sandbox analysis for arbitrary packages.
 - Tool-specific `pkgwhy agent judge` expansion beyond the current package precheck path.
 - `pkgwhy agent explain-decision <review-id>`.
@@ -197,6 +216,58 @@ Emit machine-readable judgement JSON:
 pkgwhy judge typer --json
 ```
 
+Before installing a package, run a local precheck:
+
+```bash
+pkgwhy precheck typer --json
+pkgwhy precheck "typer==0.12.5" --json
+pkgwhy precheck -r requirements.txt --json
+pkgwhy precheck pyproject.toml --json
+```
+
+By default, `pkgwhy precheck` uses local installed metadata when available and does not use the network. Add `--pypi` or `--osv` only when you want explicit online enrichment. Add `--download-artifacts` to query PyPI, download one wheel or source artifact, verify its SHA-256 when PyPI metadata provides it, extract it to a temporary review directory, inspect it statically, and delete the temporary files. The command does not install, import, or execute inspected package code.
+
+For CI or install-gate usage, add `--enforce-exit-code`:
+
+```bash
+pkgwhy precheck typer --json --enforce-exit-code
+```
+
+Exit codes are:
+
+- `0`: allow.
+- `1`: allow with caution or manual review.
+- `2`: block or sandbox-only.
+- `4`: requested online/artifact lookup was unavailable or failed.
+
+To gate an install, use `pkgwhy pip install` instead of raw `pip install`:
+
+```bash
+pkgwhy pip install typer
+pkgwhy pip install typer --policy strict
+pkgwhy pip install -r requirements.txt
+pkgwhy pip install typer --dry-run --json
+```
+
+The pip gate always runs precheck first. It invokes pip only when the precheck policy allows the install, or when a human uses an explicit override flag. Review/caution results exit `1`, block/sandbox-only results exit `2`, tool/config errors exit `3`, and unavailable or incomplete requested evidence exits `4`. `--dry-run` evaluates the gate and writes the local decision log without invoking pip.
+
+Overrides are explicit:
+
+```bash
+pkgwhy pip install typer --override-review --override-reason "reviewed local evidence"
+pkgwhy pip install suspicious-name --override-block --override-reason "temporary isolated test"
+```
+
+Agents and automated workflows should use `pkgwhy pip install` when dependency policy is required, not raw `pip install`. The command is still decision support: it does not prove a package is safe and it does not sandbox pip or installed package code.
+
+For CI package gates, start from the reusable GitHub Actions template:
+
+```text
+examples/github-actions/pkgwhy-package-gate.yml
+```
+
+See [CI Templates](docs/ci-templates.md) for advisory, strict, and agent-mode usage. The template does not require secrets or a hosted `pkgwhy` service.
+
 Inspect the default agent policy and run a conservative agent precheck:
 
 ```bash
@@ -669,6 +740,7 @@ Release and process references:
 - [1.0.0 Feature Surface](docs/release-candidate-surface.md)
 - [Threat Model](docs/threat-model.md)
 - [Production Readiness Blockers](docs/production-readiness.md)
+- [Commercial And Agent Platform Direction](docs/commercial-agent-platform.md)
 
 ## Roadmap
 

{pkgwhy-1.0.0 → pkgwhy-1.5.0}/README.md

@@ -6,11 +6,11 @@ Know why a package exists before you or your agent trusts it.
 
 ## Status
 
-`pkgwhy` 1.0.0 is a Python supply-chain security decision-support tool for developers and AI agents. It is useful for local package inspection, conservative static package review, agent-readable JSON, vulnerability and provenance foundations, policy checks, and the local private-registry and runner MVP.
+`pkgwhy` 1.5.0 is a Python supply-chain security decision-support tool and local pip/CI install gate for developers and AI agents. It is useful for local package inspection, conservative static package review, agent-readable JSON, vulnerability and provenance foundations, policy checks, artifact precheck, guarded pip installs, CI package-gate templates, local registry trust states, commercial/agent platform planning, and the local private-registry and runner MVP.
 
 It is not a production security scanner, not malware-detection certainty, and not a full sandbox. Results are evidence and signals for review, not proof that a package is safe or malicious.
 
-Current packaged version: `1.0.0`.
+Current packaged version: `1.5.0`.
 
 ## What Works Now
 
@@ -22,6 +22,13 @@ pkgwhy explain typer
 pkgwhy why typer
 pkgwhy inspect typer
 pkgwhy judge typer --json
+pkgwhy precheck typer --json
+pkgwhy precheck "typer==0.12.5" --json
+pkgwhy precheck -r requirements.txt --json
+pkgwhy precheck pyproject.toml --json
+pkgwhy precheck annotated-doc==0.0.4 --download-artifacts --json
+pkgwhy pip install typer --dry-run
+pkgwhy pip install -r requirements.txt --dry-run
 pkgwhy agent policy --json
 pkgwhy agent precheck typer --json
 pkgwhy risk typer
@@ -51,6 +58,13 @@ Implemented capabilities include:
 - Metadata-derived provenance/source-trust fields from installed metadata and optional PyPI JSON, with unsupported attestation and trusted-publishing checks marked as unknown or not implemented.
 - Conservative risk level, decision, warning, recommendation, evidence, confidence, risk model version, and rule-ID output.
 - Human `inspect`, `risk`, and `judge` reports that show compact rule-evidence summaries, while JSON reports include structured rule details.
+- Pre-install package precheck for package requirements, requirements files, and `pyproject.toml` dependencies.
+- Explicit artifact-download precheck that downloads a PyPI wheel or source artifact to a temporary review directory, verifies SHA-256 when available, extracts safely, statically inspects files, and deletes temporary files by default.
+- Optional gate exit codes via `pkgwhy precheck --enforce-exit-code`.
+- Guarded pip install flow via `pkgwhy pip install`, with precheck first, stable exit codes, explicit overrides, and compact local decision logs.
+- Reusable GitHub Actions package-gate template with advisory, strict, and agent modes.
+- Local registry trust states for private tools: `trusted`, `reviewed`, `quarantined`, `blocked`, and `unknown`.
+- Commercial and agent platform architecture documentation for future local policy packs, team review, hosted evidence cache, shared organization policy, and agent install gateway.
 - Stable JSON output for agent workflows.
 - Schema-versioned agent policy and package precheck output.
 - Conservative non-interactive agent defaults that block unknown or high-risk package use until a human reviews the evidence.
@@ -64,6 +78,9 @@ pkgwhy registry list
 pkgwhy registry add local-copy ~/.pkgwhy/registry
 pkgwhy registry use local
 pkgwhy publish ./my_tool.py
+pkgwhy registry trust local/my_tool
+pkgwhy registry quarantine local/my_tool
+pkgwhy registry blocked
 pkgwhy tool inspect local/my_tool
 pkgwhy tool judge local/my_tool --json
 pkgwhy run local/my_tool
@@ -85,6 +102,7 @@ Current runner policy is intentionally conservative:
 - Corrupt registry indexes fail closed for publish and tool-judgement paths.
 - Symlinks are not bundled, and stored registry paths must remain inside the registry root.
 - Bundle hash mismatch or a missing bundle blocks execution.
+- Quarantined or blocked registry trust states block execution.
 - `sandbox_only` and `block` tool judgements block execution.
 - Non-interactive execution is blocked unless both the judgement and manifest agent policy allow it.
 - Tools with declared dependencies are not run yet because dependency installation is not implemented.
@@ -98,11 +116,12 @@ These are roadmap items, not current features:
 
 - Complete vulnerability database coverage, transitive vulnerability analysis, or guaranteed advisory freshness.
 - Default online vulnerability lookup. Network access is only used when explicitly requested.
-- Cached PyPI/source lookup beyond the current OSV response cache.
+- Persistent cached PyPI/source lookup beyond the current OSV response cache.
 - Cloud/private remote registry backends.
 - `pull`, mirroring, and remote synchronization.
 - Tool dependency installation in the runner.
 - Tool bundle signing and signature verification.
+- Tool lock/verify commands and registry export/import.
 - Dynamic sandbox analysis for arbitrary packages.
 - Tool-specific `pkgwhy agent judge` expansion beyond the current package precheck path.
 - `pkgwhy agent explain-decision <review-id>`.
@@ -161,6 +180,58 @@ Emit machine-readable judgement JSON:
 pkgwhy judge typer --json
 ```
 
+Before installing a package, run a local precheck:
+
+```bash
+pkgwhy precheck typer --json
+pkgwhy precheck "typer==0.12.5" --json
+pkgwhy precheck -r requirements.txt --json
+pkgwhy precheck pyproject.toml --json
+```
+
+By default, `pkgwhy precheck` uses local installed metadata when available and does not use the network. Add `--pypi` or `--osv` only when you want explicit online enrichment. Add `--download-artifacts` to query PyPI, download one wheel or source artifact, verify its SHA-256 when PyPI metadata provides it, extract it to a temporary review directory, inspect it statically, and delete the temporary files. The command does not install, import, or execute inspected package code.
+
+For CI or install-gate usage, add `--enforce-exit-code`:
+
+```bash
+pkgwhy precheck typer --json --enforce-exit-code
+```
+
+Exit codes are:
+
+- `0`: allow.
+- `1`: allow with caution or manual review.
+- `2`: block or sandbox-only.
+- `4`: requested online/artifact lookup was unavailable or failed.
+
+To gate an install, use `pkgwhy pip install` instead of raw `pip install`:
+
+```bash
+pkgwhy pip install typer
+pkgwhy pip install typer --policy strict
+pkgwhy pip install -r requirements.txt
+pkgwhy pip install typer --dry-run --json
+```
+
+The pip gate always runs precheck first. It invokes pip only when the precheck policy allows the install, or when a human uses an explicit override flag. Review/caution results exit `1`, block/sandbox-only results exit `2`, tool/config errors exit `3`, and unavailable or incomplete requested evidence exits `4`. `--dry-run` evaluates the gate and writes the local decision log without invoking pip.
+
+Overrides are explicit:
+
+```bash
+pkgwhy pip install typer --override-review --override-reason "reviewed local evidence"
+pkgwhy pip install suspicious-name --override-block --override-reason "temporary isolated test"
+```
+
+Agents and automated workflows should use `pkgwhy pip install` when dependency policy is required, not raw `pip install`. The command is still decision support: it does not prove a package is safe and it does not sandbox pip or installed package code.
+
+For CI package gates, start from the reusable GitHub Actions template:
+
+```text
+examples/github-actions/pkgwhy-package-gate.yml
+```
+
+See [CI Templates](docs/ci-templates.md) for advisory, strict, and agent-mode usage. The template does not require secrets or a hosted `pkgwhy` service.
+
 Inspect the default agent policy and run a conservative agent precheck:
 
 ```bash
@@ -633,6 +704,7 @@ Release and process references:
 - [1.0.0 Feature Surface](docs/release-candidate-surface.md)
 - [Threat Model](docs/threat-model.md)
 - [Production Readiness Blockers](docs/production-readiness.md)
+- [Commercial And Agent Platform Direction](docs/commercial-agent-platform.md)
 
 ## Roadmap
 

{pkgwhy-1.0.0 → pkgwhy-1.5.0}/SECURITY.md

@@ -2,7 +2,7 @@
 
 ## Supported Status
 
-`pkgwhy` 1.0.0 includes static evidence hardening, vulnerability/provenance foundations, static rule corpus/schema hardening, release/process hardening, a safe-fail experimental dynamic command skeleton, agent policy foundations, and local registry/runner hardening. It is not a production malware scanner and should not be treated as a definitive malware detector or full sandbox.
+`pkgwhy` 1.5.0 includes static evidence hardening, vulnerability/provenance foundations, static rule corpus/schema hardening, release/process hardening, a safe-fail experimental dynamic command skeleton, agent policy foundations, local pre-install and pip install gates, reusable CI package-gate templates, local registry trust states, commercial/agent platform planning, and local registry/runner hardening. It is not a production malware scanner and should not be treated as a definitive malware detector or full sandbox.
 
 ## Reporting Security Issues
 
@@ -36,6 +36,16 @@ The local runner blocks missing or hash-mismatched bundles, corrupt registry ind
 
 Local registry publishing blocks duplicate owner/name/version records and rejects symlinks in tool bundles. Registry-stored manifest and bundle paths must resolve inside the registry root.
 
+Local registry trust states are local policy labels. New tools default to `unknown`. `trusted` and `reviewed` are human-maintained labels, not cryptographic verification. `quarantined` and `blocked` tools are refused by the local runner before execution.
+
+Pre-install package gate commands are decision support. `pkgwhy precheck <package> --json` checks package requirements before installation and can optionally query PyPI/OSV or download artifacts only when explicit flags request that work. Artifact precheck downloads to a temporary review directory, verifies SHA-256 when PyPI metadata provides it, statically inspects files, and deletes temporary files by default. It does not install, import, or execute inspected package code.
+
+Pip install gate commands are also decision support. `pkgwhy pip install <package>` and `pkgwhy pip install -r requirements.txt` run precheck before invoking pip. Pip is invoked only when policy allows or when a human uses an explicit override flag. The gate logs compact local decision summaries when possible, but those logs are not tamper-proof audit records. The pip gate does not sandbox pip, installed package code, build backends, or install-time behavior.
+
+CI templates are local workflow scaffolding. They install and run the local `pkgwhy` CLI, write reports, and optionally fail jobs based on configured mode. They do not contact a hosted `pkgwhy` service, provide a cloud review, or require secrets for basic use.
+
+Commercial and agent platform documentation is roadmap-only. The current release does not configure hosted review, billing, payment providers, API keys, cloud services, remote policy enforcement, or shared accounts.
+
 Agent policy commands are decision support. `pkgwhy agent precheck <package> --json` applies conservative policy to package judgement JSON and defaults to blocking unknown or high-risk package use in non-interactive mode until a human reviews the evidence. Agent decision logs are local compact summaries, best-effort when the config directory is writable, and intentionally omit full package evidence. They are not a tamper-proof audit system.
 
 Runner warning:
@@ -54,7 +64,9 @@ Dynamic analysis is a separate experimental roadmap area and is not part of the
 - Full source distribution versus wheel comparison is not implemented yet.
 - No runner dependency installation yet.
 - No tool bundle signing or signature verification yet.
+- No tool lock/verify commands or registry export/import yet.
 - No tamper-proof audit log, remote attestation, or signed decision record yet.
+- No sandboxed pip execution; `pkgwhy pip install` is a policy gate before pip, not an installer sandbox.
 - No tool-specific agent judgement beyond the current package precheck alias yet.
 - No cloud registry, remote pull, hosted review API, or account-based registry auth yet.
 - Typosquatting detection is heuristic and conservative. It can miss risky names and can surface false positives.

pkgwhy-1.5.0/docs/ci-templates.md

@@ -0,0 +1,77 @@
+# CI Templates
+
+`pkgwhy` can run as a local CI package gate without a cloud service, API key, or secret.
+
+The reusable GitHub Actions template is:
+
+```text
+examples/github-actions/pkgwhy-package-gate.yml
+```
+
+Copy it into a repository as `.github/workflows/pkgwhy-package-gate.yml` and choose a mode with `PKGWHY_MODE`.
+
+## Modes
+
+- `advisory`: produce reports and never fail the job.
+- `strict`: fail when `pkgwhy precheck -r requirements.txt --enforce-exit-code` returns review, block, or unavailable-evidence exit codes.
+- `agent`: use the same dependency-file gate as strict mode and optionally run `pkgwhy agent precheck "$PKGWHY_AGENT_PACKAGE" --json`.
+
+## Reports
+
+The template writes:
+
+- `pkgwhy-reports/precheck.json`
+- `pkgwhy-reports/audit.json`
+- `pkgwhy-reports/audit.md`
+- `pkgwhy-reports/agent-precheck.json` when `PKGWHY_MODE=agent` and `PKGWHY_AGENT_PACKAGE` is set.
+
+The template uploads those reports with `actions/upload-artifact`.
+
+## Advisory Mode
+
+Use advisory mode while introducing the gate:
+
+```yaml
+env:
+  PKGWHY_MODE: advisory
+```
+
+This mode is report-only. It does not claim packages are safe and does not block a pull request.
+
+## Strict Mode
+
+Use strict mode when dependency changes should be blocked until precheck allows them:
+
+```yaml
+env:
+  PKGWHY_MODE: strict
+```
+
+Strict mode uses the precheck exit code:
+
+- `0`: allow.
+- `1`: review or caution.
+- `2`: block or sandbox-only.
+- `4`: requested evidence was unavailable or incomplete.
+
+Any non-zero precheck exit fails the job.
+
+## Agent Mode
+
+Use agent mode for repositories where automated agents should not install dependencies without a precheck:
+
+```yaml
+env:
+  PKGWHY_MODE: agent
+  PKGWHY_AGENT_PACKAGE: typer
+```
+
+Agent mode is still local decision support. It does not prove package safety, run a hosted review, or sandbox pip.
+
+## Boundaries
+
+- No secrets are required for basic use.
+- No hosted `pkgwhy` service is contacted.
+- OSV.dev or PyPI lookups happen only if you add explicit flags to the template.
+- Static analysis signals are evidence for review, not proof of malicious or safe behavior.
+- `pkgwhy pip install` should be used instead of raw `pip install` when install policy is required.

pkgwhy-1.5.0/docs/commercial-agent-platform.md

@@ -0,0 +1,135 @@
+# Commercial And Agent Platform Direction
+
+`pkgwhy` is a local-first package decision-support CLI before it is a hosted product. The commercial direction is to make `pkgwhy` the install gate before `pip install` for humans, CI systems, and AI coding agents:
+
+```bash
+pkgwhy precheck <package>
+pkgwhy pip install <package>
+pkgwhy agent precheck <package> --json
+```
+
+Core message:
+
+- Before pip install, ask why.
+- Stop AI agents from pip-installing mystery code.
+- Treat `pkgwhy` output as decision support, not proof that code is safe or malicious.
+
+This document is architecture and roadmap only. It does not configure a hosted service, billing system, API key, cloud registry, remote review backend, or secrets.
+
+## Local Free CLI
+
+The free local CLI remains the foundation:
+
+- offline-first installed package inspection;
+- metadata, manifest, lockfile, and source-file review;
+- static capability and readability signals;
+- local vulnerability/provenance enrichment when configured;
+- `precheck` before installation;
+- `pip install` gate over precheck;
+- agent-readable JSON and conservative exit codes;
+- local private-tool registry and runner;
+- local trust labels for private tools.
+
+The local CLI should keep working without a network connection, hosted account, API key, or model provider.
+
+## Pro Local Policy Packs
+
+Future Pro policy packs may add stronger local policy configuration while keeping enforcement on the user's machine:
+
+- organization-ready deny and allow rules;
+- curated trusted package baselines;
+- stricter agent install policies;
+- saved review profiles for common environments;
+- local report signing when signing support exists;
+- richer local audit history.
+
+Policy packs must not pretend to provide malware certainty or full sandboxing. They should make review decisions more consistent and easier to enforce.
+
+## Team And Cloud Review Dashboard
+
+A future team dashboard may coordinate package reviews across users and repositories:
+
+- review queues for package requests;
+- shared decisions with expiry dates;
+- links to package evidence and local CLI JSON;
+- policy exceptions with named approvers;
+- historical review records;
+- team-level policy distribution.
+
+This is not implemented in the current release. The current repository contains no hosted service, account system, payment flow, or remote review API.
+
+## Hosted Package Review Cache
+
+A future hosted cache may store source-grounded package review evidence so teams and agents do not repeat the same lookup work:
+
+- package metadata snapshots;
+- artifact hashes and static inspection summaries;
+- known vulnerability source snapshots;
+- provenance and repository metadata snapshots;
+- review freshness timestamps;
+- privacy controls for private package names and internal decisions.
+
+Hosted cache output should be source-attributed and freshness-aware. Missing hosted evidence must not be treated as proof that a package is safe.
+
+## Shared Organization Policy
+
+Shared policy should make agent behavior predictable:
+
+- block raw public installs by default where required;
+- require `pkgwhy precheck` or `pkgwhy pip install`;
+- allow trusted internal packages;
+- quarantine packages under review;
+- block known-bad or policy-disallowed packages;
+- require explicit human override reasons.
+
+Policy enforcement should remain conservative. A policy decision can block or require review; it should not claim that a package is definitively safe.
+
+## Agent Install Gateway
+
+The agent install gateway is the commercial platform boundary for AI coding agents. Its job is to turn a package install request into a reviewable decision:
+
+1. Agent requests a package install.
+2. Gateway runs or requires `pkgwhy precheck`.
+3. Policy decides allow, caution, review, sandbox-only, or block.
+4. Allowed installs go through `pkgwhy pip install` or a controlled package source.
+5. Review-required and blocked installs return structured JSON for the agent.
+6. Human overrides require explicit reason logging.
+
+The local implementation today is `pkgwhy agent precheck` plus `pkgwhy pip install`. A hosted gateway is future work and must not silently install unknown public packages.
+
+## MCP And Agent Gateway Design
+
+A future MCP or agent gateway can expose a small, explicit tool surface:
+
+- `precheck_package(package_spec, policy_mode)`;
+- `pip_install_package(package_spec, policy_mode, override_reason)`;
+- `explain_decision(review_id)`;
+- `list_policy()`;
+- `request_human_review(package_spec, evidence)`;
+- `record_override(review_id, reason)`.
+
+The gateway should return schema-versioned JSON, avoid executing inspected package code, and fail closed when data is unavailable. It should not expose a raw unrestricted package-install tool.
+
+## Hosted Review Boundaries
+
+Hosted review is future only in this release:
+
+- no cloud service is configured;
+- no billing provider is configured;
+- no API keys are required;
+- no secrets are stored;
+- no package names or review data are uploaded by the local CLI unless a future explicit feature says so;
+- no cloud result is fabricated;
+- no hosted decision is treated as definitive malware detection.
+
+## Roadmap Tiers
+
+Planned product tiers are design targets, not active billing:
+
+- Free local CLI: precheck, pip gate, local JSON, local registry, and local trust labels.
+- Pro local policy packs: stricter local rules, saved profiles, local reports, and team-ready defaults.
+- Team review dashboard: shared package decisions, approvals, policy exceptions, and review history.
+- Hosted package review cache: source-grounded cached package evidence with freshness and privacy controls.
+- Agent install gateway: controlled package installation boundary for AI agents.
+
+The next engineering step is to deepen local policy and registry trust before any hosted review or commercial account system is built.

{pkgwhy-1.0.0 → pkgwhy-1.5.0}/docs/json-schema-compatibility.md

@@ -7,16 +7,19 @@ Public command JSON is offline-first by default. Optional online enrichment, suc
 Current public JSON contracts:
 
 - `pkgwhy.package_judgement.v1` for `pkgwhy judge <package> --json` and embedded package judgements.
+- `pkgwhy.precheck.v1` for `pkgwhy precheck <package> --json`.
+- `pkgwhy.precheck_batch.v1` for `pkgwhy precheck -r requirements.txt --json` and `pkgwhy precheck pyproject.toml --json`.
+- `pkgwhy.pip_install_gate.v1` for `pkgwhy pip install <package> --json` and `pkgwhy pip install -r requirements.txt --json`.
 - `pkgwhy.audit.v2` for `pkgwhy audit --json`.
 - `pkgwhy.agent_policy.v1` for `pkgwhy agent policy --json`.
 - `pkgwhy.agent_package_precheck.v1` for `pkgwhy agent precheck <package> --json` and `pkgwhy agent judge <package> --json`.
-- `pkgwhy.tool_judgement.v1` for `pkgwhy tool judge <tool> --json`.
+- `pkgwhy.tool_judgement.v1` for `pkgwhy tool judge <tool> --json`, including local registry `trust_state`.
 - `pkgwhy.tool_manifest.v1` for local private-tool manifests embedded in tool judgement JSON.
 - `pkgwhy.dynamic_analysis.v1` for experimental dynamic-analysis JSON.
 
 ## Compatibility Rules
 
-During the 1.0.0 release line, schema versions are compatibility surfaces for agent workflows. Changes should be deliberate:
+During the current 1.x release line, schema versions are compatibility surfaces for agent workflows. Changes should be deliberate:
 
 - Additive optional fields may keep the same schema version when existing consumers can ignore them safely.
 - Required field additions, removals, renamed fields, enum meaning changes, or nested shape changes must bump the affected schema version.
@@ -24,11 +27,16 @@ During the 1.0.0 release line, schema versions are compatibility surfaces for ag
 - Schema versions are not reused for different incompatible shapes.
 - Compatibility changes must be documented in `CHANGELOG.md`.
 
-## Snapshot Coverage
+## Test Coverage
 
-The test suite includes normalized golden snapshots for:
+The test suite includes normalized golden snapshots or focused schema validation for:
 
 - `pkgwhy judge <package> --json`
+- `pkgwhy precheck <package> --json`
+- `pkgwhy precheck -r requirements.txt --json`
+- `pkgwhy precheck pyproject.toml --json`
+- `pkgwhy pip install <package> --json`
+- `pkgwhy pip install -r requirements.txt --json`
 - `pkgwhy audit --json`
 - `pkgwhy agent precheck <package> --json`
 - `pkgwhy agent judge <package> --json`

{pkgwhy-1.0.0 → pkgwhy-1.5.0}/docs/release-checklist.md

@@ -32,6 +32,12 @@ Run CLI smokes:
 .venv/bin/python -m pkgwhy judge typer --json
 .venv/bin/python -m pkgwhy risk typer
 .venv/bin/python -m pkgwhy audit --limit 2 --json
+.venv/bin/python -m pkgwhy precheck typer --json
+.venv/bin/python -m pkgwhy precheck -r tests/fixtures/precheck/requirements.txt --json
+.venv/bin/python -m pkgwhy precheck pyproject.toml --json
+.venv/bin/python -m pkgwhy pip --help
+.venv/bin/python -m pkgwhy pip install --help
+.venv/bin/python -m pkgwhy pip install typer --dry-run --json
 .venv/bin/python -m pkgwhy typos requests pandas-stubs
 .venv/bin/python -m pkgwhy agent --help
 .venv/bin/python -m pkgwhy agent precheck typer --json