patchdrill 0.1.0

package/docs/DASHBOARD.md

@@ -0,0 +1,87 @@
+# Static HTML Dashboard
+
+PatchDrill can write a self-contained HTML dashboard for local review and CI artifacts. It has no external assets, no network calls, and uses the same deterministic report data as Markdown, JSON, and SARIF output.
+
+Generate the dashboard during a scan:
+
+```bash
+patchdrill scan --base origin/main --run \
+  --evidence patchdrill-evidence.json \
+  --summary-markdown patchdrill-summary.md \
+  --markdown patchdrill-report.md \
+  --json patchdrill-report.json \
+  --sarif patchdrill.sarif \
+  --html patchdrill-dashboard.html
+patchdrill verify --evidence patchdrill-evidence.json
+```
+
+Re-render a dashboard from a saved JSON report:
+
+```bash
+patchdrill dashboard --json patchdrill-report.json --output patchdrill-dashboard.html
+```
+
+Saved JSON reports must satisfy the report contract before PatchDrill renders a dashboard. This prevents old reports without required verification metadata from being repackaged as current evidence.
+
+Render a dashboard with CI artifact history by passing reports in oldest-to-newest order. The last `--json` is the current report used for the main dashboard, and earlier reports populate the run trend table.
+
+```bash
+patchdrill dashboard \
+  --json reports/patchdrill-previous.json \
+  --json reports/patchdrill-current.json \
+  --output patchdrill-dashboard.html
+```
+
+The dashboard includes:
+
+- Status, risk, confidence, changed-file, required-check, and added-line summary metrics.
+- Multi-run risk and failed-check trends when repeated JSON reports are provided.
+- Findings with severity, rule IDs, locations, tags, and remediation.
+- Verification plans with per-command status, plus captured command results.
+- Changed files, project signals, policy context, baseline context, owner context, and dependency changes.
+
+For CI, upload the HTML alongside the JSON, Markdown, and evidence artifacts:
+
+```yaml
+- 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"
+- 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 }}
+```
+
+If your workflow downloads one or more previous JSON report artifacts before running PatchDrill, pass them through `dashboard-history`. PatchDrill appends the current JSON report automatically and re-renders the HTML dashboard with the trend table:
+
+```yaml
+- 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"
+    dashboard-history: |
+      reports/patchdrill-previous.json
+      reports/patchdrill-last-green.json
+```

package/docs/EVIDENCE.md

@@ -0,0 +1,55 @@
+# Proof Packs and Evidence Manifests
+
+A Proof Pack is the portable evidence bundle PatchDrill creates for a patch. It can contain a compact Markdown summary, full Markdown report, JSON report, SARIF report, self-contained HTML dashboard, and a JSON evidence manifest.
+
+The evidence manifest is the verifiable index for that bundle. It records artifact metadata and command-output digests so a reviewer or CI system can later prove which files belonged to the same scan:
+
+```bash
+patchdrill scan --base origin/main --run \
+  --evidence patchdrill-evidence.json \
+  --summary-markdown patchdrill-summary.md \
+  --markdown patchdrill-report.md \
+  --json patchdrill-report.json \
+  --sarif patchdrill.sarif \
+  --html patchdrill-dashboard.html
+```
+
+`scan --evidence` requires `--json` because the verifier needs a JSON report artifact to cross-check the report digest and report contract.
+
+The manifest includes:
+
+- The PatchDrill report SHA-256 and byte length.
+- SHA-256 digests for generated Markdown, JSON, SARIF, HTML, and compact-summary artifacts.
+- Command result metadata with stdout and stderr digests, not raw command output.
+- The PatchDrill version and report schema version that produced the bundle.
+- Local git branch, head SHA, and base SHA when available.
+- The same summary scores used by the JSON report and dashboard.
+
+If a scan infers or configures required verification commands but no matching command results are present, the report includes a `verification.required-not-run` finding. This keeps local scans non-mutating by default while making missing evidence visible in the same report and evidence bundle.
+
+Human-facing reports also render a plan-to-result verification matrix. Each planned command is labeled as passed, failed, timed out, not run, or skipped optional, so reviewers do not have to manually join `commandPlan` and `commandResults` to see which evidence is present. JSON reports must include the same computed `verification` section for bots and dashboards, and `patchdrill verify --evidence` rejects a JSON report when that section is missing or drifts from the underlying command plan and command results.
+
+Verify a saved manifest against its artifacts:
+
+```bash
+patchdrill verify --evidence patchdrill-evidence.json
+```
+
+Verification checks that recorded artifact SHA-256 values and byte lengths still match the files on disk. When a JSON report artifact is present, PatchDrill also cross-checks it against the manifest's report digest, verifies that the manifest summary, report counts, command result metadata, command-output digests, and required structured verification status still match the JSON report, and rejects JSON reports whose summary counts no longer match their changed files, command plan, or command results.
+
+Regenerate a manifest after post-processing final artifacts, such as re-rendering a dashboard with trend history:
+
+```bash
+patchdrill evidence \
+  --json patchdrill-report.json \
+  --evidence patchdrill-evidence.json \
+  --summary-markdown patchdrill-summary.md \
+  --markdown patchdrill-report.md \
+  --sarif patchdrill.sarif \
+  --html patchdrill-dashboard.html
+patchdrill verify --evidence patchdrill-evidence.json
+```
+
+`patchdrill evidence` validates the saved JSON report contract before writing the regenerated manifest.
+
+This keeps the default scanner local-only and deterministic while giving CI systems one small file that can prove which Proof Pack artifacts belonged to a run.

package/docs/LAUNCH_PLAYBOOK.md

@@ -0,0 +1,103 @@
+# Launch Playbook
+
+PatchDrill is designed for developers who already use AI coding agents and want a concrete, repeatable answer to "what proves this patch?"
+
+## Positioning
+
+One-liner:
+
+> PatchDrill is the deterministic proof layer between code review and CI for AI-generated and human patches.
+
+Short pitch:
+
+> AI agents can write code quickly, but reviewers still need evidence. PatchDrill reads a git diff, infers what should be tested, flags risky areas, and writes a portable Proof Pack for local review, CI, audit trails, and model-assisted review.
+
+Comparison:
+
+- AI PR reviewers judge whether a patch looks right.
+- Traditional CI runs commands that were already configured.
+- SAST/SCA scanners match known code, dependency, and vulnerability rules.
+- Review automation posts configured comments and annotations.
+- PatchDrill turns the patch itself into a repeatable verification plan, risk report, policy gate, and Proof Pack.
+
+## Launch Checklist
+
+Done for the public repository:
+
+- Public GitHub repository with CodeQL, OpenSSF Scorecard, Dependabot, issue forms, pull request template, and repository topics.
+- Self-contained GitHub Action that builds from the checked-out action source before running PatchDrill.
+- Proof Pack outputs: SARIF, Markdown, JSON, compact PR summary, static HTML dashboard, and verifiable evidence manifest.
+- Generated PR workflow runs inferred required commands with a per-command timeout.
+- README terminal demo asset showing the risk summary and portable report outputs.
+- Package automation script findings for install-time hooks, removed verification scripts, no-op checks, and remote shell pipes.
+- First-party fixtures for more than five popular stacks, including Node/Turborepo, Python, Rails, Terraform, Docker/Compose, Kubernetes, Java/Gradle, .NET, SwiftPM, Xcode, Bazel, Buck2, Pants, Cargo, and Go.
+- Example report and release provenance documentation.
+- `patchdrill doctor` for first-run repository readiness diagnosis.
+- `patchdrill release-check` for static npm/GitHub Action release readiness checks.
+- CI and release workflows dogfood `patchdrill release-check --format json`.
+- CI/action/release workflows verify generated evidence manifests before artifacts or packages are trusted; release smoke includes required command evidence.
+- JSON Schemas for policy, report, evidence, doctor, and release-check automation contracts.
+- Public case-study and stack-coverage docs for launch evaluation.
+- Release readiness checks local Markdown links across README, docs, and examples.
+- Release readiness checks package file allowlisting and launch-discovery keywords.
+
+Still needed for launch distribution:
+
+- Publish npm package as `patchdrill`.
+- Move the `v0` GitHub Action tag after each compatible 0.x action update.
+- Dogfood on 20 external real pull requests and add anonymized example reports.
+- Submit to GitHub Trending-adjacent communities: Hacker News Show HN, r/programming, r/ClaudeCode, r/codex, r/opensource, DevTools directories.
+- Write a blog post: "AI made patches faster. Here is how to make review evidence faster too."
+
+## Demo Script
+
+```bash
+git checkout -b demo/auth-change
+echo "// pretend auth change" >> src/auth/session.ts
+patchdrill scan
+patchdrill scan --run \
+  --evidence patchdrill-evidence.json \
+  --summary-markdown patchdrill-summary.md \
+  --markdown patchdrill-report.md \
+  --json patchdrill-report.json \
+  --sarif patchdrill.sarif \
+  --html patchdrill-dashboard.html
+patchdrill verify --evidence patchdrill-evidence.json
+```
+
+Show:
+
+- High-impact auth finding.
+- Missing test-change finding.
+- Inferred commands from `package.json`.
+- Package script findings when a patch changes install hooks or weakens test scripts.
+- Proof Pack artifact bundle.
+- SARIF upload in GitHub code scanning.
+- `.patchdrill.yml` policy rule that requires owner review for a sensitive path.
+
+## Release Gate
+
+Run this before creating the first public release:
+
+```bash
+patchdrill doctor
+patchdrill release-check
+patchdrill release-check --format json
+npm run check
+node dist/cli.js scan --evidence .patchdrill/release-evidence.json --summary-markdown .patchdrill/release-summary.md --markdown .patchdrill/release.md --json .patchdrill/release.json --sarif .patchdrill/release.sarif --html .patchdrill/release-dashboard.html --run --fail-on critical
+node dist/cli.js verify --evidence .patchdrill/release-evidence.json
+npm pack --dry-run
+```
+
+`release-check` verifies local repository readiness, including parseable shipped JSON Schemas, matching README/SCHEMAS documentation for every public schema command, JSON-backed evidence verification in CI/action/release workflows, README and pull request Proof Pack command checklists, synchronized stack-coverage docs, stack fixture contracts, and committed demo artifact synchronization. npm Trusted Publisher configuration still has to be checked in npm account settings.
+
+## Star Hooks
+
+- "No LLM required."
+- "Proof Packs over vibes."
+- "Not another AI reviewer. A deterministic safety gate."
+- "Works before your CI bill grows."
+- "Review the plan before running commands."
+- "Markdown for humans, JSON for bots, SARIF for GitHub."
+- "Detects prompt-injection strings before agents ingest them."
+- "Catches install-time package scripts and no-op test rewrites."

package/docs/MONOREPOS.md

@@ -0,0 +1,74 @@
+# Monorepo Targeting
+
+PatchDrill detects Node, Cargo, Go, and Pants workspaces, including nested Cargo and Go workspaces inside polyglot monorepos, and reports the affected packages or native changed-target plan for a diff.
+
+Supported Node workspace metadata:
+
+- `package.json` with `workspaces: []`
+- `package.json` with `workspaces.packages`
+- `pnpm-workspace.yaml`
+
+When a changed file sits under a workspace package, PatchDrill emits package-scoped verification commands for that package and downstream workspace packages that depend on it:
+
+| Package manager | Example |
+| --- | --- |
+| npm | `npm --workspace @acme/api run test` |
+| pnpm | `pnpm --filter @acme/api run test` |
+| yarn | `yarn workspace @acme/api test` |
+| bun | `bun --filter @acme/api run test` |
+
+PatchDrill reads workspace `dependencies`, `devDependencies`, `peerDependencies`, and `optionalDependencies`, keeps only dependencies that point to other workspace packages, and expands affected packages transitively. If `@acme/web` depends on `@acme/api` and `@acme/api` depends on `@acme/shared`, a change in `@acme/shared` marks all three packages as affected.
+
+Root-wide files such as lockfiles, root `package.json`, `pnpm-workspace.yaml`, `turbo.json`, and `nx.json` still mark all workspace packages as affected.
+
+## Native Task Runners
+
+PatchDrill detects `turbo.json`, `nx.json`, root `turbo`/`nx` dependencies, and root scripts that invoke `turbo` or `nx`. When a supported task runner is present, workspace plans use the native task graph:
+
+| Runner | Example |
+| --- | --- |
+| Turborepo | `pnpm exec turbo run test --filter=@acme/api` |
+| Nx | `npx nx run api:test` |
+
+Turborepo plans still use package names from `package.json`. Nx plans use `project.json` names when present, otherwise the package name. If a package has no script but `project.json` declares a matching target, PatchDrill can still plan `test`, `build`, `lint`, or `typecheck` through Nx.
+
+For Node package scripts, PatchDrill recognizes common aliases such as `check:types`, `test:unit`, and optional browser/e2e checks like `test:e2e`, `playwright`, and `cypress`. This keeps inferred plans useful for real front-end and full-stack repositories without forcing every package to expose only `test` and `typecheck`.
+
+## Cargo Workspaces
+
+PatchDrill reads `[workspace].members` from root `Cargo.toml`, expands member globs, reads each member crate name, and keeps workspace-internal crate dependencies. A change under `crates/core` marks that crate as affected and also marks downstream workspace crates that depend on it.
+
+| Change | Example command |
+| --- | --- |
+| Direct crate change | `cargo test -p core-lib --all-targets` |
+| Downstream dependent crate | `cargo test -p api-server --all-targets` |
+| Optional lint plan | `cargo clippy -p core-lib --all-targets -- -D warnings` |
+
+## Go Workspaces
+
+PatchDrill reads `go.work` `use` entries, each module's `module` path, and workspace-internal `require` dependencies. A change under `modules/core` marks that module as affected and also marks downstream workspace modules that require it. If the Go workspace is nested under a polyglot root, commands run from that nested workspace root.
+
+| Change | Example command |
+| --- | --- |
+| Direct module change | `go test ./modules/core/...` |
+| Downstream dependent module | `go test ./modules/api/...` |
+| Nested workspace module change | `cd services/go && go test ./modules/core/...` |
+| Optional static check | `go vet ./modules/core/...` |
+
+## Pants Repositories
+
+PatchDrill detects `pants.toml` and uses Pants' native Git-aware target selection instead of reconstructing Pants target graphs. For local uncommitted work it plans against `HEAD`; for `patchdrill scan --base origin/main`, it plans against `origin/main`.
+
+| Goal | Example command |
+| --- | --- |
+| Required tests | `pants --changed-since=origin/main --changed-dependents=transitive test` |
+| Optional lint | `pants --changed-since=origin/main --changed-dependents=transitive lint` |
+| Optional checks | `pants --changed-since=origin/main --changed-dependents=transitive check` |
+
+## Why This Matters
+
+Large repositories need targeted evidence. Running only root commands can hide which package proved the change, while running every package wastes CI time. PatchDrill keeps the plan explicit: affected package, command, and reason appear in Markdown and JSON reports.
+
+## Current Scope
+
+PatchDrill builds workspace impact from package manifests, then hands task execution to native graph engines when available: Turborepo, Nx, and Pants.

package/docs/POLICY.md

@@ -0,0 +1,98 @@
+# Policy-As-Code
+
+PatchDrill reads `.patchdrill.yml`, `.patchdrill.yaml`, or `.patchdrill.json` from the repository root. You can also pass a custom path:
+
+```bash
+patchdrill scan --config security/patchdrill.yml
+```
+
+Policy files are validated when loaded. Invalid severities, unknown fields, malformed command entries, duplicate command IDs or command strings, conflicting aliases, and malformed rules fail the scan instead of being silently ignored.
+
+Create a starter policy:
+
+```bash
+patchdrill init --policy
+```
+
+Create a stricter starter pack:
+
+```bash
+patchdrill init --policy-pack regulated
+patchdrill init --policy-pack agentic
+```
+
+Built-in packs:
+
+| Pack | Focus |
+| --- | --- |
+| `default` | General repo hygiene and agent instruction review. |
+| `regulated` | Payments, identity/access, data migrations, release infrastructure, and lower default risk tolerance. |
+| `agentic` | Agent instructions, MCP/tool configs, prompt templates, and AI workflow trust boundaries. |
+
+## Example
+
+```yaml
+failOn: high
+maxRisk: 69
+
+ignoredPaths:
+  - generated/**
+  - dist/**
+
+requiredCommands:
+  - id: contract-tests
+    label: API contract tests
+    command: npm run test:contracts
+    reason: API surfaces changed.
+
+optionalCommands:
+  - id: playwright-smoke
+    label: Browser smoke test
+    command: npm run test:smoke
+    reason: UI routes changed.
+
+rules:
+  - id: payments-owner-review
+    title: Payments owner review required
+    severity: critical
+    path: src/payments/**
+    detail: Payment logic is high-impact and needs domain-owner sign-off.
+    remediation: Add reviewer notes with test evidence, rollback notes, and owner approval.
+    tags:
+      - payments
+      - owner-review
+```
+
+## Fields
+
+| Field | Purpose |
+| --- | --- |
+| `failOn` | Default CLI failure threshold when `--fail-on` is not passed. |
+| `maxRisk` | Default numeric risk threshold when `--max-risk` is not passed. |
+| `ignoredPaths` | Glob patterns removed from changed-file and added-line analysis. |
+| `requiredCommands` | Commands PatchDrill runs when `--run` is set. |
+| `optionalCommands` | Commands shown in the report and run only when both `--run` and `--run-optional` are set. |
+| `rules` | Path-based findings with custom severity, weight, remediation, and tags. |
+
+Policy commands are merged with inferred commands by command string and ID. If a policy `requiredCommands` entry matches an inferred optional command, PatchDrill promotes the merged command to required so repo policy cannot be weakened by a generic detector.
+
+Within a policy file, command IDs and command strings must be unique across `requiredCommands` and `optionalCommands`. Use either `ignoredPaths` or `ignore`, not both; use either `path` or `paths` in each rule, not both.
+
+## Glob Support
+
+PatchDrill supports `*`, `**`, and `?` path globs.
+
+```yaml
+ignoredPaths:
+  - generated/**
+  - "**/*.snap"
+```
+
+## Review Guidance
+
+Use policy for repo-specific invariants that generic tools cannot know:
+
+- Domain-owner review for payments, permissions, or ML model policy.
+- Extra contract tests for public API schema changes.
+- Release-manager review for deployment and infrastructure paths.
+- Generated-code ignore rules where source-of-truth files are reviewed elsewhere.

package/docs/PROOF_PACKS.md

@@ -0,0 +1,57 @@
+# Proof Packs
+
+A Proof Pack is the reviewable evidence bundle PatchDrill generates for one patch. It is designed to be small enough for pull request review, structured enough for bots, and verifiable enough for audit trails.
+
+PatchDrill does not replace reviewer judgment. It gives reviewers the same deterministic evidence every time the same diff is scanned.
+
+## Contents
+
+| Artifact | Audience | Use |
+| --- | --- | --- |
+| Compact Markdown summary | Pull request reviewers | Shows status, risk, top findings, and required commands in a short comment or step summary. |
+| Full Markdown report | Human reviewers | Provides changed files, command plan, findings, dependency changes, package script changes, and command results. |
+| JSON report | Bots and dashboards | Preserves the complete report contract, including required structured verification status, for policy gates and custom tooling. |
+| SARIF report | GitHub code scanning | Turns findings into code scanning alerts with stable fingerprints. |
+| HTML dashboard | Humans and CI artifacts | Gives a self-contained visual report, including optional trend history from prior JSON reports. |
+| Evidence manifest | CI and audit trails | Records the PatchDrill version, report metadata, artifact digests, command metadata, and command-output digests so the bundle can be verified later. |
+
+## Review Flow
+
+1. Run `patchdrill scan --base origin/main` locally to see the plan without running commands.
+2. Run `patchdrill scan --base origin/main --run` when the inferred required commands look right.
+3. Attach or upload the Proof Pack artifacts in CI.
+4. Review the findings and failed commands before asking an AI reviewer or human reviewer for higher-level judgment.
+5. Verify the evidence manifest if artifacts are post-processed or audited later.
+
+## CI Flow
+
+```bash
+patchdrill scan --base origin/main --run \
+  --evidence patchdrill-evidence.json \
+  --summary-markdown patchdrill-summary.md \
+  --markdown patchdrill-report.md \
+  --json patchdrill-report.json \
+  --sarif patchdrill.sarif \
+  --html patchdrill-dashboard.html \
+  --fail-on high \
+  --max-risk 69
+
+patchdrill verify --evidence patchdrill-evidence.json
+```
+
+This keeps the scanner deterministic and local-first while still producing artifacts that CI gates, auditors, bots, and reviewers can inspect.
+
+## Why It Matters
+
+AI PR reviewers are useful for judgment, explanation, and design feedback. They are not a durable source of proof. A Proof Pack gives that judgment layer concrete input:
+
+- The exact files and lines that changed.
+- The ecosystems and workspace scopes touched by the patch.
+- The commands PatchDrill inferred from the patch.
+- Which required commands ran, failed, timed out, or still lack evidence.
+- Which optional commands were skipped unless `--run-optional` was used.
+- Which risk rules increased the score.
+- Which artifacts belonged to the same scan.
+- Which PatchDrill version, report metadata, and command-output digests produced the evidence bundle.
+
+The intended workflow is not "trust PatchDrill instead of reviewers." It is "make the proof explicit before reviewers spend attention."

package/docs/PR_COMMENTS.md

@@ -0,0 +1,56 @@
+# Pull Request Comments
+
+PatchDrill's composite GitHub Action can upsert a compact Markdown summary as a pull request comment.
+
+```yaml
+permissions:
+  contents: read
+  pull-requests: write
+  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"
+      pr-comment: "true"
+      comment-marker: "<!-- patchdrill-report -->"
+  - 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 }}
+```
+
+PatchDrill finds an existing bot comment containing the marker and updates it. If no marker is present, it creates a new comment. The comment uses the compact summary by default, while the full Markdown, JSON, SARIF, and HTML reports remain available as workflow artifacts.
+
+Set `pr-comment: "false"` to skip comment writes while keeping the step summary, annotations, SARIF, HTML, JSON, Markdown, and evidence artifacts. The Action accepts `"true"`, `"false"`, `"1"`, `"0"`, `"yes"`, `"no"`, `"on"`, and `"off"` for boolean inputs.
+
+To preview the comment body without opening a pull request, run:
+
+```bash
+patchdrill demo --scenario risky-agent-pr --output patchdrill-risky-demo
+cat patchdrill-risky-demo/patchdrill-demo-summary.md
+```
+
+## Permissions
+
+The workflow needs `pull-requests: write` to create or update PR comments. Keep other permissions least-privileged.
+
+For fork pull requests where the workflow token is read-only, PatchDrill emits a warning and skips the comment instead of failing the verification run. The step summary, annotations, SARIF, HTML, JSON, Markdown, and evidence artifacts still remain available.

package/docs/RELEASE.md

@@ -0,0 +1,35 @@
+# Release
+
+PatchDrill is configured for npm trusted publishing and provenance through `.github/workflows/release.yml`.
+
+## npm Trusted Publishing
+
+Configure the npm package as a trusted publisher for this repository and the `Release` workflow. npm trusted publishing uses OIDC from GitHub Actions and automatically produces provenance attestations when publishing from the trusted workflow.
+
+## Release Flow
+
+1. Update `package.json` version and `CHANGELOG.md`.
+2. Run local verification:
+
+```bash
+patchdrill doctor
+patchdrill release-check
+patchdrill release-check --format json
+patchdrill schema doctor
+patchdrill schema release-check
+npm run check
+node dist/cli.js scan --evidence .patchdrill/release-evidence.json --summary-markdown .patchdrill/release-summary.md --markdown .patchdrill/release.md --json .patchdrill/release.json --sarif .patchdrill/release.sarif --html .patchdrill/release-dashboard.html --run --fail-on critical
+node dist/cli.js verify --evidence .patchdrill/release-evidence.json
+npm pack --dry-run
+```
+
+3. Create a GitHub Release for the version tag.
+4. The `Release` workflow runs build, tests, package dry-run, and `npm publish --provenance`.
+
+## Dry Run
+
+Use `workflow_dispatch` to run release checks without publishing. Publishing is limited to GitHub Release events.
+
+`patchdrill release-check` is intentionally local and static. It verifies package metadata, package file allowlisting, launch keywords, action wiring, command-backed evidence verification in CI/action/release workflows, release workflow provenance settings, README install paths, repository release files, README and pull request Proof Pack command checklists, parseable shipped JSON Schemas with matching README/SCHEMAS documentation, synchronized stack-coverage docs, stack fixture contracts, committed demo artifact synchronization, and local Markdown links across README, docs, and examples. It cannot verify the npm account-side Trusted Publisher setup; check that in npm before publishing.
+
+CI and the release workflow both run `patchdrill release-check --format json` after `npm run check` so launch-readiness regressions fail before package publishing.