patchdrill 0.1.0

package/docs/ROADMAP.md

@@ -0,0 +1,152 @@
+# Roadmap
+
+## Near Term
+
+- Expand first-party fixtures toward the full top 20 open-source stacks.
+- Expand native affected-task integrations beyond Turborepo, Nx, Pants, Cargo, Go, Bazel, and Buck workspaces.
+- Add anonymized real-repository Proof Pack case studies for common AI-agent PR failures.
+- Split large planner and dependency modules into ecosystem-focused adapters without changing the public report schema.
+
+## Later
+
+- Expand language-aware changed-test matching with more framework-specific conventions.
+- Optional MCP server for coding agents.
+- Optional LLM summarization that can only summarize deterministic findings.
+- Rule confidence calibration from anonymized fixture corpora.
+- Local TUI for interactively accepting or rejecting inferred verification commands.
+- `patchdrill doctor` for explaining weak project detection, missing scripts, and why a command was or was not inferred.
+
+## Completed In 0.1.x
+
+- SARIF output for GitHub code scanning.
+- Policy file support: `.patchdrill.yml`.
+- Added-line scanning for secret-looking values.
+- Prompt-injection detection for agent-visible files.
+- Agent-control and MCP configuration risk rules.
+- SARIF partial fingerprints for stable GitHub code scanning alerts.
+- CodeQL, OpenSSF Scorecard, and Dependabot repository posture.
+- Direct Node workspace package targeting.
+- npm trusted publishing and provenance release workflow.
+- package.json dependency diff summaries.
+- Pull request comment upsert mode for the GitHub Action.
+- JSON Schemas for policy, report, evidence, doctor, and release-check contracts.
+- Workspace dependency graph expansion for downstream package testing.
+- npm `package-lock.json` dependency diff summaries.
+- `pnpm-lock.yaml` dependency diff summaries.
+- `yarn.lock` dependency diff summaries.
+- `go.mod` dependency diff summaries.
+- `go.sum` dependency diff summaries.
+- `Cargo.toml` dependency diff summaries.
+- `Cargo.lock` dependency diff summaries.
+- Maven `pom.xml` dependency diff summaries.
+- Gradle `build.gradle` and `build.gradle.kts` dependency diff summaries.
+- Gradle `libs.versions.toml` version catalog dependency diff summaries.
+- `requirements.txt` dependency diff summaries.
+- `poetry.lock` dependency diff summaries.
+- `uv.lock` dependency diff summaries.
+- `Pipfile.lock` dependency diff summaries.
+- `bun.lock` dependency diff summaries.
+- `Gemfile` dependency diff summaries.
+- `Gemfile.lock` dependency diff summaries.
+- `composer.lock` dependency diff summaries.
+- `composer.json` dependency diff summaries.
+- CODEOWNERS owner hints for changed files.
+- Baseline comparison against previous JSON reports.
+- `--max-risk-delta` gating for baseline regressions.
+- `patchdrill init --policy` starter policy generation.
+- npm package metadata for repository discovery.
+- Architecture docs and action examples for the public package path.
+- CI dogfooding with PatchDrill SARIF and report artifacts.
+- Current-format example report covering Markdown sections.
+- GitHub issue forms and pull request template for contributor intake.
+- `schemaVersion` in JSON and Markdown reports.
+- `pyproject.toml` PEP 621 and Poetry dependency diff summaries.
+- Native Turborepo and Nx task-runner plans for affected Node workspaces.
+- Binary `bun.lockb` migration guidance for legacy Bun projects.
+- Organization policy packs for regulated and agentic-code teams.
+- Cargo workspace task plans for affected crates and downstream dependents.
+- Go workspace task plans for affected modules and downstream dependents.
+- First-party stack fixture harness covering Node/Turborepo, Next.js, Python, Rails, PHP/Composer, Terraform, Docker/Compose, Pants, Cargo, and Go services.
+- Native Pants changed-target task plans.
+- Language-aware source-to-test matching for risk scoring.
+- Static HTML dashboard generation from scan output and saved JSON reports.
+- Composite GitHub Action support for HTML dashboard artifacts.
+- Kubernetes and Helm manifest verification planning.
+- First-party stack fixtures for Kustomize, Java/Gradle, and .NET services.
+- Bazel and Buck2 workspace detection with graph-wide verification planning.
+- Swift Package Manager verification planning.
+- Xcode project/workspace detection with shared-scheme verification planning.
+- Django framework detection with `manage.py test` and `manage.py check` planning.
+- Spring Boot framework detection with Gradle `bootJar` packaging plans.
+- Android Gradle detection with debug unit test, assemble, and lint planning.
+- ASP.NET Core detection with .NET build and publish planning.
+- FastAPI app entrypoint detection with import-smoke planning.
+- FastAPI changed router/dependency module import-smoke planning.
+- GitHub Actions supply-chain findings for unpinned actions, remote script pipes, and untrusted PR metadata interpolation.
+- Bazel and Buck2 changed-package target narrowing with graph-wide fallback for root metadata changes.
+- Bazel/Buck reverse-dependency query commands for downstream affected-target discovery.
+- Bazel/Buck downstream reverse-dependency query promotion into optional executable test plans.
+- .NET project-aware test, build, and ASP.NET Core publish planning through `ProjectReference` relationships.
+- Android Gradle variant-aware test, assemble, and lint planning from changed source sets.
+- Android product-flavor source set parsing for debug variant task planning.
+- Context-aware GitHub Actions finding for `pull_request_target` workflows that check out pull request head code.
+- Python and FastAPI changed-test targeting for matching pytest files with whole-suite fallback.
+- Whole-file GitHub Actions context analysis for changed workflows with pre-existing privileged triggers or checkout steps.
+- NuGet PackageReference and central PackageVersion dependency change summaries.
+- Workflow trust-boundary findings for reusable workflows that use `secrets: inherit`, including mutable remote reusable workflow refs.
+- Workflow trust-boundary findings for `pull_request_target` OIDC token minting, environment-scoped OIDC jobs, and remote reusable workflows receiving caller OIDC permissions.
+- .NET solution filter targeting for very large solutions.
+- FastAPI dependency override test targeting for changed dependency helper functions.
+- .NET solution-filter selection for changed projects when multiple overlapping `.slnf` files exist.
+- Xcode `.xctestplan` detection from shared schemes and `xcodebuild test -testPlan` planning.
+- Android generated-source variant detection and `variantFilter` disabled-variant avoidance.
+- Nested local reusable workflow loading for downstream reusable workflow secret and OIDC trust-boundary findings.
+- Cloud OIDC credential exchange findings for AWS, Azure, GCP, and Vault auth jobs without GitHub environment protection.
+- Xcode scheme target-platform detection with macOS test destinations, mobile generic build destinations, and destination discovery planning.
+- Rails, RSpec, Composer script, Laravel, PHPUnit, and PHP syntax fallback command planning.
+- Multi-run static dashboard trends for CI artifact history.
+- GitHub Action `dashboard-history` input for re-rendering trend dashboards from previous JSON report artifacts.
+- Framework-specific changed-test matching for Rails/RSpec, Python app packages, JVM source sets, and Laravel unit/feature tests.
+- Node script alias planning for typecheck, unit, and optional browser/e2e verification scripts.
+- uv-managed Python fixture and optional Ruff, mypy, and Pyright static-analysis planning.
+- Nested Python package-root detection with scoped pytest, compile, and optional static-analysis plans.
+- Nested Cargo workspace detection with `--manifest-path` crate and downstream-dependent verification plans.
+- Nested Go module and workspace detection with scoped `go test` and `go vet` plans.
+- `--run-optional` CLI and GitHub Action opt-in for executing optional verification commands.
+- `patchdrill demo` plus committed synchronized first-run sample Markdown, JSON, SARIF, and HTML artifacts.
+- GitHub Actions annotation output and documentation for findings.
+- Generated workflow templates that explicitly enable annotations and step summaries.
+- Compact Markdown summaries for GitHub step summaries and pull request comments.
+- First-party Maven and Spring Boot Maven stack fixtures.
+- Audit evidence manifests with report, artifact, and command-output digests.
+- Evidence manifest verification against generated artifact hashes.
+- Evidence manifest verification against JSON report summary and count metadata.
+- Evidence manifest verification against JSON report internal summary consistency.
+- Evidence manifest verification against JSON report command metadata and command-output digests.
+- Launch packaging with 30-second demo guidance, public case studies, and stack coverage matrix.
+- `patchdrill doctor` for first-run repository readiness diagnosis.
+- `patchdrill release-check` for local npm/GitHub Action release readiness checks.
+- Named dependency analyzer registry and planner ecosystem introspection for coverage and architecture reporting.
+- Evidence manifests record the PatchDrill tool version.
+- Evidence manifest regeneration for finalized artifacts and CI verification before upload.
+- Fail-state `risky-agent-pr` demo scenario for quick product evaluation.
+- Fork-safe PR comment handling that does not fail verification when comment permissions are unavailable.
+- Compact PR comment preview artifacts in demo output.
+- Generated PR workflows execute required verification commands with bounded per-command timeout.
+- Package automation script risk findings for lifecycle hooks, removed verification scripts, no-op checks, and remote shell pipes.
+- Structured package script change summaries in JSON, Markdown, and HTML reports.
+- Clearer `patchdrill explain` first-run guidance for teams comparing deterministic evidence with AI PR reviewers.
+- Explicit boolean CLI flag values so `--run=false` and related safety flags are not treated as enabled.
+- GitHub Action boolean inputs now share the CLI boolean vocabulary for execution, annotations, summaries, and PR comments.
+- Command-plan normalization so policy-required checks can promote matching inferred optional checks.
+- Policy loader fail-fast checks for duplicate command IDs, duplicate command strings, and conflicting aliases.
+- Missing-evidence risk findings when required verification commands were planned but not run.
+- Dependency proof-gap findings for manifest-only dependency changes and lockfile-only resolution drift.
+- Repository hygiene for default generated report artifacts after local scans.
+- Mutable `docker://` GitHub Action image findings with digest-pinned allowlisting.
+
+## Contribution Targets
+
+PatchDrill needs real-world fixtures from:
+
+- Xcode simulator and device fixture corpora for concrete iOS, visionOS, watchOS, and tvOS test destination naming.

package/docs/RULE_CATALOG.md

@@ -0,0 +1,90 @@
+# Rule Catalog
+
+Every PatchDrill risk score increase maps to a human-readable finding. This catalog lists the built-in rule IDs so teams can understand reports, write policy exceptions, and decide which findings should block merges.
+
+Policy rules from `.patchdrill.yml` use dynamic IDs in the form `policy.<rule-id>`.
+
+## Patch Size and Shape
+
+| Rule ID | What it means |
+| --- | --- |
+| `patch.changed-files` | The patch changes repository files and needs review evidence. |
+| `patch.medium` | The patch changes more than 500 lines. |
+| `patch.large` | The patch changes more than 2000 lines. |
+| `file.deleted` | A file was deleted. |
+| `file.binary` | A binary file changed. |
+
+## Sensitive Files
+
+| Rule ID | What it means |
+| --- | --- |
+| `file.secret-bearing` | A file path commonly used for credentials changed. |
+| `file.high-impact-area` | Auth, billing, migration, or security-sensitive code changed. |
+| `file.infrastructure` | Infrastructure, CI, build, or deployment behavior changed. |
+| `file.lockfile` | A dependency lockfile changed. |
+| `file.bun-lockb` | A legacy binary Bun lockfile changed. |
+| `file.dependency-manifest` | A dependency manifest changed. |
+
+## Secret Patterns
+
+| Rule ID | What it means |
+| --- | --- |
+| `secret.private-key` | Private key material was added. |
+| `secret.aws-access-key` | An AWS access key-looking value was added. |
+| `secret.github-token` | A GitHub token-looking value was added. |
+| `secret.openai-key` | An OpenAI API key-looking value was added. |
+| `secret.generic-assignment` | A secret-looking assignment was added. |
+
+## Agentic AI Surfaces
+
+| Rule ID | What it means |
+| --- | --- |
+| `agent.control-file` | Agent instruction or control files changed. |
+| `agent.mcp-config` | MCP or agent tool configuration changed. |
+| `agent.prompt-injection` | Prompt-injection-like content was added. |
+| `agent.tool-abuse-instruction` | Agent-visible content appears to encourage destructive commands or tool misuse. |
+
+## GitHub Actions Trust Boundaries
+
+| Rule ID | What it means |
+| --- | --- |
+| `workflow.pull-request-target` | A `pull_request_target` trigger was added. |
+| `workflow.write-all` | Broad `permissions: write-all` was added. |
+| `workflow.write-scope` | A GitHub token write scope was added. |
+| `workflow.inherited-secrets` | `secrets: inherit` was added. |
+| `workflow.unpinned-action` | A GitHub Action reference is mutable or missing a full commit SHA. |
+| `workflow.mutable-docker-action` | A `docker://` action image is tag-based or implicitly latest instead of digest-pinned. |
+| `workflow.remote-script-pipe` | A workflow pipes remote downloads directly into an interpreter. |
+| `workflow.untrusted-pr-context` | A workflow interpolates untrusted pull request metadata. |
+| `workflow.pull-request-target-head-checkout` | A privileged `pull_request_target` workflow checks out pull request head code. |
+| `workflow.reusable-inherited-secrets` | A reusable workflow job inherits all caller secrets. |
+| `workflow.reusable-unpinned-secret-call` | A mutable remote reusable workflow receives inherited secrets. |
+| `workflow.pull-request-target-oidc` | A fork-triggerable `pull_request_target` workflow can mint OIDC tokens. |
+| `workflow.environment-oidc-token` | A job targeting a GitHub environment can mint OIDC tokens. |
+| `workflow.cloud-oidc-without-environment` | A cloud credential exchange can mint OIDC tokens without a GitHub environment gate. |
+| `workflow.reusable-oidc-token-boundary` | A remote reusable workflow can mint caller OIDC tokens. |
+| `workflow.reusable-unpinned-oidc-call` | A mutable remote reusable workflow can mint caller OIDC tokens. |
+
+## Package Scripts
+
+| Rule ID | What it means |
+| --- | --- |
+| `package-script.remote-script-pipe` | A package script downloads remote code directly into an interpreter. |
+| `package-script.lifecycle` | An install, prepare, pack, publish, or related lifecycle script changed. |
+| `package-script.disabled-verification` | A verification script appears to have been replaced with a no-op. |
+| `package-script.removed-verification` | A conventional verification script was removed. |
+
+## Dependency Proof Gaps
+
+| Rule ID | What it means |
+| --- | --- |
+| `dependency.manifest-without-lockfile` | Direct dependency intent changed without matching lockfile evidence. |
+| `dependency.lockfile-without-manifest` | Lockfile resolution drift occurred without matching direct dependency intent. |
+
+## Verification Evidence
+
+| Rule ID | What it means |
+| --- | --- |
+| `verification.required-not-run` | Required verification commands were planned but not executed. |
+| `command.failed` | A verification command failed. |
+| `test.source-without-test-change` | Source files changed without matching test files in the patch. |

package/docs/SARIF.md

@@ -0,0 +1,74 @@
+# SARIF Output
+
+PatchDrill can emit SARIF 2.1.0 for GitHub code scanning:
+
+```bash
+patchdrill scan --base origin/main \
+  --evidence patchdrill-evidence.json \
+  --summary-markdown patchdrill-summary.md \
+  --markdown patchdrill-report.md \
+  --json patchdrill-report.json \
+  --sarif patchdrill.sarif \
+  --html patchdrill-dashboard.html \
+  --run
+patchdrill verify --evidence patchdrill-evidence.json
+```
+
+Each file-scoped finding becomes a SARIF result with:
+
+- `ruleId`: deterministic finding or policy rule ID.
+- `level`: mapped from severity.
+- `location`: file and line when available.
+- `properties`: severity and tags.
+- `partialFingerprints`: stable PatchDrill fingerprints for GitHub alert tracking.
+
+## GitHub Actions
+
+```yaml
+permissions:
+  contents: read
+  security-events: write
+
+steps:
+  - uses: actions/checkout@v6
+    with:
+      fetch-depth: 0
+  - uses: seungdori/patchdrill@v0
+    id: patchdrill
+    with:
+      base: origin/${{ github.base_ref }}
+      evidence: patchdrill-evidence.json
+      summary: patchdrill-summary.md
+      markdown: patchdrill-report.md
+      json: patchdrill-report.json
+      sarif: patchdrill.sarif
+      html: patchdrill-dashboard.html
+      run: "true"
+      fail-on: high
+      max-risk: "69"
+  - uses: github/codeql-action/upload-sarif@v4
+    if: always()
+    with:
+      sarif_file: ${{ steps.patchdrill.outputs.report-sarif }}
+  - uses: actions/upload-artifact@v7
+    if: always()
+    with:
+      name: patchdrill-report
+      path: |
+        ${{ steps.patchdrill.outputs.report-evidence }}
+        ${{ steps.patchdrill.outputs.report-markdown }}
+        ${{ steps.patchdrill.outputs.report-html }}
+        ${{ steps.patchdrill.outputs.report-json }}
+        ${{ steps.patchdrill.outputs.report-sarif }}
+        ${{ steps.patchdrill.outputs.report-summary }}
+```
+
+## Severity Mapping
+
+| PatchDrill | SARIF |
+| --- | --- |
+| `critical` | `error` |
+| `high` | `error` |
+| `medium` | `warning` |
+| `low` | `note` |
+| `info` | `note` |

package/docs/SCHEMAS.md

@@ -0,0 +1,49 @@
+# JSON Schemas
+
+PatchDrill ships JSON Schema draft 2020-12 contracts for policy files, machine-readable reports, audit evidence manifests, and readiness automation output.
+
+```bash
+patchdrill schema policy > patchdrill-policy.schema.json
+patchdrill schema report > patchdrill-report.schema.json
+patchdrill schema evidence > patchdrill-evidence.schema.json
+patchdrill schema doctor > patchdrill-doctor.schema.json
+patchdrill schema release-check > patchdrill-release-check.schema.json
+```
+
+Write a schema to a file:
+
+```bash
+patchdrill schema report --output schemas/patchdrill-report.schema.json
+```
+
+List available schemas:
+
+```bash
+patchdrill schema --list
+```
+
+## Policy Schema
+
+Use `schemas/patchdrill-policy.schema.json` to validate `.patchdrill.yml`, `.patchdrill.yaml`, or `.patchdrill.json`. The schema covers ignored paths, risk gates, policy commands, and path-matched rules.
+
+For editor completion in YAML, add a language-server schema comment:
+
+```yaml
+# yaml-language-server: $schema=./schemas/patchdrill-policy.schema.json
+```
+
+## Report Schema
+
+Use `schemas/patchdrill-report.schema.json` for bots and dashboards that consume `patchdrill scan --json`. The report includes `schemaVersion: "1"` and the schema covers summary scores, changed files, project signals, workspace package impact, dependency changes, package script changes, findings, verification plans, command results, and the required computed `verification` section that joins plans with results. Human-facing reports render the same verification matrix from the same fields. `patchdrill verify --evidence` also checks report consistency that JSON Schema cannot express, such as changed-file totals, failed-command counts, missing verification status, and verification status drift.
+
+## Evidence Schema
+
+Use `schemas/patchdrill-evidence.schema.json` for audit storage that consumes `patchdrill scan --evidence`. The manifest records the PatchDrill tool version, report digest, generated artifact digests, command-output digests, command result metadata, and local git refs without embedding raw stdout or stderr. `scan --evidence` requires `--json`, and `patchdrill verify` cross-checks those command digests and the JSON report's internal summary counts against the JSON report artifact.
+
+## Doctor Schema
+
+Use `schemas/patchdrill-doctor.schema.json` for onboarding bots and repository bootstrap checks that consume `patchdrill doctor --format json`. The report includes `schemaVersion: "1"`, readiness summary counts, detected project signals, diagnostic checks, and suggested next commands without mutating the repository.
+
+## Release-Check Schema
+
+Use `schemas/patchdrill-release-check.schema.json` for release automation that consumes `patchdrill release-check --format json`. The report includes `schemaVersion: "1"`, a top-level `ok` flag, summary counts, and local release-readiness checks for package metadata, action wiring, provenance workflow settings, launch docs, pull request and README Proof Pack commands, parseable shipped schema contracts, synchronized stack-coverage docs, stack fixture contracts, committed demo artifacts, and Markdown links.

package/docs/SECURITY_POSTURE.md

@@ -0,0 +1,32 @@
+# Security Posture
+
+PatchDrill is meant to be installed in CI and sometimes executed locally against sensitive diffs. The repository should therefore carry the same trust signals it asks users to expect from their own projects.
+
+## Automated Checks
+
+| Check | File | Purpose |
+| --- | --- | --- |
+| TypeScript build and Vitest | `.github/workflows/ci.yml` | Verifies deterministic scanner behavior and package readiness. |
+| PatchDrill self-scan | `.github/workflows/ci.yml` | Dogfoods pull request diff scanning, verifies evidence hashes, uploads SARIF, and preserves Markdown/JSON/HTML/evidence report artifacts. |
+| CodeQL | `.github/workflows/codeql.yml` | Adds GitHub-native static analysis for the TypeScript codebase. |
+| OpenSSF Scorecard | `.github/workflows/scorecard.yml` | Tracks open-source security posture and uploads SARIF results. |
+| Dependabot | `.github/dependabot.yml` | Keeps npm and GitHub Actions dependencies current. |
+| Release provenance | `.github/workflows/release.yml` | Publishes through npm trusted publishing and provenance. |
+| Hardened Action inputs | `action.yml` | Passes composite Action inputs through step environment variables and a bash array so optional paths and thresholds are not re-tokenized by the shell. |
+
+## Repository Rules To Enable On GitHub
+
+- Require pull request review before merging to `main`.
+- Require status checks: CI, CodeQL, OpenSSF Scorecard.
+- Require signed commits or vigilant mode if the maintainers use it consistently.
+- Restrict GitHub Actions permissions to least privilege by default.
+- Enable private vulnerability reporting.
+- Enable secret scanning and push protection where available.
+
+## Release Hygiene
+
+- Run `npm pack --dry-run` before publishing.
+- Review the tarball file list before every release.
+- Publish from GitHub Actions trusted publishing with provenance.
+- Keep generated reports out of git through `.gitignore`.
+- Avoid storing any real secret-like fixture in tests; synthesize test values at runtime.

package/docs/STACK_COVERAGE.md

@@ -0,0 +1,20 @@
+# Stack Coverage
+
+PatchDrill coverage is fixture-backed and deterministic. This matrix describes what the current v0.1 engine can detect, plan, and explain before merge.
+
+| Stack | Detects | Command Plans | Proof Signals |
+| --- | --- | --- | --- |
+| Node, npm, pnpm, Yarn, Bun | package.json scripts, package managers, workspaces, Turborepo, Nx, package automation scripts, JS lockfiles | typecheck, lint, unit, build, optional browser/e2e, package-scoped workspace commands, downstream dependents | dependency intent, lifecycle-script risk, no-op/removed verification scripts, manifest/lockfile proof gaps |
+| Python, uv, Django, FastAPI | pyproject.toml, requirements.txt, uv.lock, manage.py, FastAPI app entrypoints, nested Python roots | scoped pytest, Django test/check, FastAPI import smoke, optional Ruff, mypy, Pyright | changed-test matching, dependency diffs, app entrypoint smoke evidence |
+| Rust and Cargo | Cargo.toml, Cargo.lock, workspaces, nested crates, downstream local dependents | cargo test, cargo clippy, manifest-path scoped crate checks | Cargo dependency diffs, workspace impact, lockfile drift |
+| Go | go.mod, go.sum, go.work, nested modules, local replace/workspace relationships | scoped go test, go vet, downstream module checks | module dependency diffs, go.sum resolution drift |
+| Java, Maven, Gradle, Spring Boot | pom.xml, Gradle build files, version catalogs, Spring Boot manifests | Maven/Gradle tests, Gradle build, Spring Boot packaging | Maven/Gradle dependency diffs, JVM source-set test matching |
+| Android Gradle | Android Gradle plugin projects, product flavors, generated sources, disabled variant filters | debug/flavor unit tests, assemble, lint with disabled-variant avoidance | variant-aware command plans and source-set impact |
+| .NET and ASP.NET Core | .sln, .slnf, .csproj, ProjectReference graphs, central PackageVersion files, ASP.NET Core projects | solution-filter or project-scoped dotnet test, dotnet build, ASP.NET Core publish | NuGet dependency diffs and project-reference impact |
+| Ruby, Rails, PHP, Laravel | Gemfile, Gemfile.lock, Rails apps, composer.json, composer.lock, Laravel artisan | RSpec/Rails tests, Composer scripts, PHPUnit, Laravel unit/feature tests, PHP syntax fallback | Bundler/Composer dependency diffs and framework-specific test matching |
+| SwiftPM and Xcode | Package.swift, Xcode projects/workspaces, shared schemes, xctestplan files, target platforms | swift test, xcodebuild test/build with scheme, test plan, and destination guidance | Apple platform verification planning without running device-only flows by default |
+| Terraform, Docker, Kubernetes, Helm, Kustomize | Terraform files, Dockerfile/compose files, Kubernetes manifests, Helm charts, Kustomize overlays | terraform fmt/validate, docker build, docker compose config, kubectl/helm/kustomize validation | infra review findings and deployment-manifest proof requirements |
+| GitHub Actions and reusable workflows | workflow files, local reusable workflow references, OIDC, secrets inheritance, mutable actions, pull_request_target boundaries | workflow diff review and optional evidence for changed workflow surfaces | trust-boundary findings, SARIF/annotation output, release/OIDC risk evidence |
+| Bazel, Buck2, Pants | workspace metadata, package targets, changed target scopes, reverse-dependency queries | targeted test/build commands plus optional downstream rdeps queries | graph-aware fallback when root metadata changes |
+
+Use this as a public support matrix, not a claim that PatchDrill replaces stack-specific CI. PatchDrill plans the evidence that should exist; the repository still owns the actual commands and runtime dependencies.

package/docs/assets/patchdrill-demo.svg

@@ -0,0 +1,21 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="980" height="520" viewBox="0 0 980 520" role="img" aria-labelledby="title desc">
+  <title id="title">PatchDrill terminal demo</title>
+  <desc id="desc">A terminal showing PatchDrill turning an auth diff into deterministic risk findings and required verification commands.</desc>
+  <rect width="980" height="520" rx="14" fill="#0b1020"/>
+  <rect x="24" y="24" width="932" height="472" rx="10" fill="#111827" stroke="#334155"/>
+  <circle cx="52" cy="50" r="7" fill="#ef4444"/>
+  <circle cx="76" cy="50" r="7" fill="#f59e0b"/>
+  <circle cx="100" cy="50" r="7" fill="#22c55e"/>
+  <text x="126" y="55" fill="#94a3b8" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="14">patchdrill scan</text>
+  <text x="48" y="98" fill="#e5e7eb" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">$ patchdrill scan --base origin/main</text>
+  <text x="48" y="136" fill="#86efac" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">PatchDrill Gate PASS</text>
+  <text x="268" y="136" fill="#facc15" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">assessment WARN</text>
+  <text x="48" y="174" fill="#e5e7eb" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">risk 44/100  confidence 56/100</text>
+  <text x="48" y="212" fill="#cbd5e1" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">Changed files: 1, +1/-1</text>
+  <text x="48" y="250" fill="#cbd5e1" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">Required commands: 2</text>
+  <text x="48" y="300" fill="#fca5a5" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">Top findings:</text>
+  <text x="72" y="338" fill="#fecaca" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="17">[high] High-impact product area changed</text>
+  <text x="72" y="372" fill="#fed7aa" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="17">[medium] Source changed without matching test changes</text>
+  <text x="48" y="430" fill="#93c5fd" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">Reports: Markdown + JSON + SARIF + self-contained HTML</text>
+  <text x="48" y="464" fill="#94a3b8" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="16">No LLM required. Same diff, same evidence, every run.</text>
+</svg>

package/examples/case-studies/README.md

@@ -0,0 +1,20 @@
+# PatchDrill Case Studies
+
+This directory points launch readers at concrete Proof Pack scenarios.
+
+## Included
+
+| Case | Evidence | What to inspect |
+| --- | --- | --- |
+| Risky agent PR | `../risky-agent-pr` | Critical workflow boundary, secret-looking value, package lifecycle script, PR summary, SARIF, HTML |
+| Review-ready PR | `../demo` | Normal Proof Pack output with Markdown, JSON, SARIF, HTML, and compact summary |
+
+## Suggested Demo Flow
+
+```bash
+patchdrill demo --scenario risky-agent-pr --output patchdrill-risky-demo
+open patchdrill-risky-demo/patchdrill-demo.html
+cat patchdrill-risky-demo/patchdrill-demo-summary.md
+```
+
+The point is not that PatchDrill replaces review. The point is that every reviewer receives the same deterministic evidence bundle before deciding whether the patch is acceptable.

package/examples/demo/README.md

@@ -0,0 +1,21 @@
+# PatchDrill Demo Artifacts
+
+These files are generated by:
+
+```bash
+patchdrill demo --output examples/demo
+```
+
+- `patchdrill-demo-summary.md`: compact PR comment and step-summary preview.
+- `patchdrill-demo.md`: reviewer-facing Markdown report.
+- `patchdrill-demo.json`: machine-readable report contract.
+- `patchdrill-demo.sarif`: GitHub code scanning upload format.
+- `patchdrill-demo.html`: self-contained static dashboard.
+
+The test suite keeps these committed examples synchronized with the demo renderer.
+
+For a fail-state demo that shows privileged workflow, secret, agent-instruction, and billing-test findings:
+
+```bash
+patchdrill demo --scenario risky-agent-pr --output examples/risky-agent-pr
+```

package/examples/demo/patchdrill-demo-summary.md

@@ -0,0 +1,35 @@
+# PatchDrill Summary
+
+**WARN** - risk 58/100, confidence 82/100
+
+- Changed files: 5 (+186 / -42)
+- Verification plan: 3 required, 1 optional
+- Verification evidence: 3 run, 3 passed, 0 failed, 0 timed out, 0 missing required, 1 optional skipped
+- Baseline risk delta: +14 (2 new findings)
+
+## Changed Files
+
+- `apps/api/src/auth/session.ts` (modified, +54 / -16)
+- `apps/api/src/auth/session.test.ts` (modified, +48 / -4)
+- `packages/db/migrations/20260601090000_add_session_rotation.sql` (added, +38 / -0)
+- `.github/workflows/deploy.yml` (modified, +22 / -12)
+- `package-lock.json` (modified, +24 / -10)
+
+## Top Findings
+
+| Severity | Finding | Location |
+| --- | --- | --- |
+| high | High-impact product area changed | apps/api/src/auth/session.ts |
+| high | Data migration review required | packages/db/migrations/20260601090000_add_session_rotation.sql |
+| medium | OIDC deployment job should use a protected environment | .github/workflows/deploy.yml:34 |
+| low | Dependency lockfile changed | package-lock.json |
+
+## Required Checks
+
+| Command | Result |
+| --- | --- |
+| `pnpm exec turbo run typecheck --filter=@acme/api` | passed |
+| `pnpm exec turbo run test --filter=@acme/api` | passed |
+| `pnpm run test:contracts` | passed |
+
+Full Markdown, JSON, SARIF, and HTML reports remain available as CI artifacts when configured.