patchrail 0.1.1__tar.gz → 0.3.0__tar.gz

{patchrail-0.1.1 → patchrail-0.3.0}/.gitignore

@@ -1,4 +1,7 @@
 .venv/
+.venv*/
+venv/
+.DS_Store
 .pkg-smoke/
 .patchrail-release-smoke/
 __pycache__/

patchrail-0.3.0/CHANGELOG.md

@@ -0,0 +1,217 @@
+# Changelog
+
+## 0.3.0 - 2026-07-09
+
+### Fixed
+
+- Deterministic Go test failures are no longer misread as
+  `network_transient_failure` when their logs contain incidental
+  network-shaped noise (`dial tcp`, `connection refused`, `context deadline
+  exceeded`, `i/o timeout`). The classifier now defers a broad transient-network
+  match built *entirely* from these ambiguous signals to the concrete failure
+  when one also matched, so a real bug isn't mislabeled "just retry". Genuine
+  outages still classify as transient because they trip a terminal signal (DNS
+  resolution, rate limit, gateway error, TLS handshake, or a git remote hang-up)
+  outside the ambiguous set. `go_test_failure` also now recognises the canonical
+  `--- FAIL:` marker. New `go-integration-test-network-noise` fixture guards this,
+  bringing the benchmark zoo to 208 cases.
+
+### Added
+
+- `patchrail --version` now prints the installed version (e.g. `patchrail 0.3.0`)
+  and exits, so a maintainer can confirm which release they are running without
+  invoking a subcommand.
+- `java_build_failure` now also recognises **sbt** (Scala on the JVM). sbt prints
+  none of the Maven/Gradle banners the rule keyed on, so a genuine
+  `(project / Test / compileIncremental) Compilation failed` — or an
+  `sbt.TestsFailedException` — previously fell through to `unknown`. New signals
+  cover the sbt session banner, incremental-compile failure, Scala
+  `not found: value`/`not found: type` errors, and the sbt test-failure
+  exception; the reproduction command now suggests `sbt test`. New sanitized
+  `github-actions-sbt-scala-compile` fixture (modelled on a real
+  `scalatest/scalatest` GitHub Actions run) guards this, bringing the benchmark
+  zoo to 209 cases.
+- New sanitized `ruby-rspec-parallel-failure` fixture captures a real
+  `rubocop/rubocop` RSpec failure tail (parallel/turbo_tests summary with
+  `pending` before `failures`), bringing the benchmark zoo to 207 cases.
+- New `xcode_build_failure` class classifies Apple-platform build and test
+  failures from `xcodebuild`, `swift build`/`swift test`, and Swift Package
+  Manager — Swift compile errors, missing modules (`error: no such module`),
+  unresolved package dependencies, and XCTest failures (`** BUILD FAILED **`,
+  `** TEST FAILED **`, `The following build commands failed:`). Backed by three
+  sanitized fixtures in `examples/ci-triage/`, bringing the benchmark zoo to 169
+  cases and the classifier to 40 failure classes.
+- New `docs_build_failure` class classifies documentation-site build failures
+  from Sphinx (`sphinx-build -W` warnings-as-errors, missing toctree entries),
+  MkDocs (`mkdocs build --strict` broken links), and Docusaurus (`docusaurus
+  build` broken links). Backed by three sanitized fixtures in
+  `examples/ci-triage/`, bringing the benchmark zoo to 166 cases.
+- `patchrail ci classes` lists every supported failure class with its likely
+  subsystem and reproduction command (plus the `unknown` fallback), in stable
+  order. Supports `--format text|json|markdown` and `--out`, so the set of
+  classes the classifier can diagnose is discoverable from the CLI instead of
+  only in the source. Closes #150.
+
+### Fixed
+
+- Real RSpec failures now classify as `ruby_bundle_failure` instead of
+  `unknown`. RSpec prints its rerun list as `rspec ./path/to/thing_spec.rb[…]`
+  and its summary as `N examples, [K pending, ]M failures` (rspec, parallel and
+  turbo_tests) — neither of which the old `rspec .*failures?` pattern matched,
+  so a pasted spec-failure tail without bundler setup lines fell through to
+  `unknown`. Two shape-matching patterns were added to the rule. Surfaced by
+  dogfooding a real `rubocop/rubocop` CI run.
+- Python CI logs no longer misclassify as `python_dependency_resolution` just
+  because they run `python -m pip install`. That bare command line was a
+  detection pattern, but it appears in almost every Python CI job regardless of
+  what actually failed, so any failing Python job with no stronger signal was
+  reported as a dependency-resolution conflict with the misleading "pin or relax
+  the conflicting dependency range" advice. Dogfooded against a real
+  `pandas-dev/pandas` 32-bit CI run whose `pip install` failed at
+  `metadata-generation-failed` (a package build error, `Rust not found`) — it was
+  reported as `python_dependency_resolution` (0.53). The boilerplate pattern is
+  dropped, so a build/metadata failure with no genuine resolution signal now
+  stays honest (`unknown`) instead. To keep recall on real conflicts, two
+  genuine pip signals were added: pip's actual Requires-Python wording
+  (`requires a different Python:`) and its no-distribution `(from versions: …)`
+  line; the three synthetic no-matching-distribution fixtures were updated to
+  include the real `(from versions: …)` output pip prints. Benchmark stays at
+  206/206 top-1 with all confidence floors met; the bundled dependency-failure
+  demo now reports 0.89 (three genuine resolution signals) instead of 0.95.
+  Regression covered in `tests/`.
+- `patchrail ci explain`/`classify` no longer hangs on large CI logs. The
+  `github_actions_workflow` rule paired two unanchored lookaheads
+  (`(?=[\s\S]*.github/workflows/…)(?=[\s\S]*Invalid workflow file…)`); under
+  `re.search` that compound is retried at every start position, so a log that
+  mentions `.github/workflows/*.yml` (every `actions/checkout` step does) but not
+  a workflow-error phrase drove the matcher into O(n²) backtracking and pegged a
+  core at 100% for minutes. Dogfooded against a real `cli/cli` Go CI run
+  (~200 KB) that never returned. The lookahead is now anchored with `\A` so it is
+  evaluated once, in linear time; the "workflow path AND error phrase present"
+  signal is unchanged. Regression covered in `tests/`.
+- Rust CI failures no longer misclassify as `node_dependency_install`,
+  `dotnet_build_failure`, or `java_build_failure` because of generic boilerplate.
+  The `Swatinem/rust-cache` action prints `Lockfiles considered:` (which matched
+  the old bare `lockfile` node signal) and cargo prints `build failed, waiting
+  for other jobs to finish` (which matched the case-insensitive `Build FAILED` /
+  `BUILD FAILED` banners). The node lockfile signal now requires a whole-word
+  `lockfile`, and the .NET/Gradle banners are matched case-sensitively so they
+  fire only on the tool's actual `Build FAILED` / `BUILD FAILED` output. A real
+  `tokio-rs/tokio` rustdoc failure (`error[E0433]`) now classifies as
+  `rust_test_failure`. Regression covered in `tests/`.
+- Sharper reproduce commands for three failure classes surfaced by `patchrail ci
+  classes` / `ci explain`. `node_script_missing` no longer suggests `npm run
+  build` (which just re-triggers the "missing script" error) and instead runs
+  `npm run` to list the scripts `package.json` actually defines, so you can
+  compare against the one your workflow calls. `security_scan_failure` names the
+  concrete scanners to rerun locally (`npm audit`, `pip-audit`, `cargo audit`,
+  `trivy fs .`, `bandit -r .`, `semgrep --config auto`) instead of the generic
+  "rerun the failing security scan locally". `github_actions_workflow` points at
+  `actionlint .github/workflows/`, which validates workflow syntax and action
+  refs locally, rather than only printing the YAML back with `gh workflow view`.
+- Real GitHub Actions logs no longer misclassify as `git_checkout_failure` when
+  checkout actually succeeded. The rule dropped three boilerplate signals that
+  appear in almost every Actions log regardless of outcome — the `actions/checkout`
+  setup step, the `git submodule foreach` post-job cleanup line, and a bare
+  `git-lfs` mention — keeping only genuine checkout/clone/submodule/LFS *failure*
+  markers (`fatal: ...`, `Failed to fetch submodule`, `smudge filter lfs failed`,
+  `error downloading object`, …). Dogfooded against a real `pallets/flask` CI run
+  whose pytest jobs failed on a conftest `SyntaxError` but were reported as a git
+  checkout problem.
+- `python_test_failure` now also recognizes pytest collection failures
+  (`ImportError while loading conftest ...`, `N errors during collection`), so a
+  broken `conftest.py` or import-time error surfaces as a test failure with the
+  `python -m pytest -q` reproduce line instead of falling through to a weaker or
+  wrong class.
+- `patchrail ci explain` and `ci classify` now fail clearly on empty or
+  whitespace-only input (from `--log` or stdin) instead of silently reporting
+  `failure_class: unknown` with confidence `0.15` and exit code `0`. They print
+  `log input is empty` to stderr, exit with code `2`, and write nothing to
+  `--out`, so a bad shell redirect is no longer mistaken for an unclassifiable
+  log. Closes #151.
+- Added `node_script_missing` to the published `ci-result` schema enum; the
+  classifier could already emit it, so a valid classification previously failed
+  schema validation for downstream consumers. A new test guards that every rule
+  class is declared in the schema enum.
+
+## 0.2.0 - 2026-07-07
+
+### Removed
+
+- Removed the commercial `Guide:` link that `ci explain` appended to text and
+  Markdown reports, and the matching guide URL outputs from the GitHub Action.
+  Reports now end after the classification; per-class remediation write-ups
+  live in-repo under `docs/fix/`.
+- Removed commercial product links and campaign-tagged URLs from the README,
+  docs, and the PyPI project URL list.
+- Removed the distribution and web-metrics tooling (`ci share-links` and the
+  web metrics commands and store). PatchRail no longer ships link-tracking or
+  distribution helpers.
+
+### Changed
+
+- `funded-issues` is now explicitly labeled experimental. Discovery commands
+  default to safe-only filtering, and risky entries require an explicit
+  `--include-risky` flag.
+- Rewrote the README around the open-source CI triage workflow: quickstart
+  with real classifier output, honest feature table, local-first safety
+  section, and the fixture contribution path.
+
+### Added
+
+- Added `node_script_missing` CI classification so npm/pnpm/yarn jobs that
+  call a missing package script are separated from dependency-install failures
+  and routed to a workflow/script repair path.
+- Added a permanent source-level blocklist to the funded-issues tracker:
+  owners manually verified as fake-bounty sources are dropped at the
+  `merge_into_store` choke point (counted as `blocked` in the merge summary)
+  and `purge_blocklisted_entries` removes any legacy entries; `track` runs the
+  purge on every merge so existing stores self-heal.
+- Added `funded-issues import-algora-board`, an offline parser for a locally
+  saved Algora organization bounty-board page. It extracts the funder-stated
+  USD amount, GitHub issue reference, posting age, and declared claim count
+  per bounty, and can merge the scored records into a tracker store. No
+  network access is performed.
+- Added read-only competition and payout-vs-effort scoring signals plus the
+  `funded-issues competition` and `funded-issues payout-effort` batch
+  commands, all derived from public metadata observations with no claims,
+  comments, or maintainer contact.
+- Added an offline owner-level `source_noise` heuristic and
+  `funded-issues apply-recheck`, a local-file-only command that transitions
+  tracker entries to closed / stale / active from recheck observations.
+- Added .NET/NuGet/C# and xUnit fixture coverage for `dotnet restore`,
+  `dotnet build`, and `dotnet test` failure modes, growing the public CI
+  fixture zoo to 153 cases.
+
+## 0.1.1 - 2026-06-12
+
+- `ci explain` now ends text and Markdown reports with a `Guide:` link to the
+  matching getpatchrail.com `/fix` remediation page; unknown or unpublished
+  failure classes fall back to the `/fix` index without a network call.
+- Added `funded-issues fresh`, a local read-only radar over the tracker store
+  that surfaces recently posted or recently labeled funded issues for fast
+  solver-side triage.
+- Added `pre_commit_hook_failure` CI classification so pre-commit hook output is
+  recognized directly while the CLI still avoids linking to a missing `/fix`
+  page until that guide exists.
+
+## 0.1.0 - 2026-06-02
+
+- Initial public CI Janitor snapshot.
+- Added `patchrail ci explain` and `patchrail ci classify`.
+- Added local Markdown, JSON, and text reports.
+- Added Apache-2.0 license and safety/ethics documentation.
+- Added fixture-backed tests, local benchmark command, and GitHub Actions CI.
+- Expanded the initial CI fixture zoo to 101 sanitized synthetic examples across
+  Python, Node, TypeScript, Go, Rust, and GitHub Actions failure modes.
+- Added a read-only GitHub Actions triage artifact workflow.
+- Added the experimental local Agent Control Plane queue with SQLite-backed
+  work items, approval states, audit export, CI result import, and proposal
+  records.
+- Added the experimental read-only `funded-issues` CLI over local metadata,
+  with safe-only filtering and explicit anti-abuse blocked actions.
+- Added permission-only adopter reporting and a public metrics tracker for
+  pilot outcomes, adoption signals, and open-source program evidence gaps.
+- Added release-prep evidence docs, package smoke checks, and manual publish
+  gates. Release tags, PyPI publishing, GitHub Releases, and public
+  announcements remain maintainer actions.

{patchrail-0.1.1 → patchrail-0.3.0}/CONTRIBUTING.md

@@ -22,7 +22,8 @@ patchrail redact --log failed-ci.log > failed-ci.redacted.log
 
 3. Review `failed-ci.redacted.log` manually and remove anything PatchRail should
    not publish: secrets, emails, private repo names, user names, customer names,
-   local home paths, and private URLs.
+   local home paths, and private URLs. See `docs/redaction.md` for exactly
+   which categories `patchrail redact` covers and which it doesn't.
 4. Reduce the log to the shortest excerpt that still shows the root cause.
 5. Add the fixture and expected metadata under `examples/ci-triage/`.
 6. Run the fixture hygiene gate and benchmark:
@@ -38,6 +39,10 @@ patchrail ci benchmark examples/ci-triage --format json
 If a real log cannot be safely redacted, create a minimal synthetic fixture that
 preserves the error pattern without preserving private identifiers.
 
+To catch a forgotten secret or a malformed fixture before it reaches a pull
+request, see `docs/pre-commit-example.md` for an optional pre-commit hook
+that runs `patchrail ci fixture-check` and `patchrail redact` automatically.
+
 ## Adding a CI fixture
 
 1. Copy the smallest failing log excerpt that still shows the root cause.

patchrail-0.3.0/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: patchrail
+Version: 0.3.0
+Summary: Local-first maintainer automation for open-source CI triage
+Project-URL: Homepage, https://github.com/patchrail/patchrail
+Project-URL: Documentation, https://github.com/patchrail/patchrail/tree/main/docs
+Project-URL: Changelog, https://github.com/patchrail/patchrail/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/patchrail/patchrail/issues
+Project-URL: GitHub Action, https://github.com/patchrail/ci-triage-action
+Author: Pablo Guillén
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: ci,github-actions,maintenance,open-source,triage
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: twine>=5.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# PatchRail
+
+Local-first CI failure triage for open-source maintainers. Paste a failing CI
+log, get the failure class, the reproduction command, and a suggested fix
+strategy — in seconds, fully offline.
+
+[![PyPI](https://img.shields.io/pypi/v/patchrail)](https://pypi.org/project/patchrail/)
+[![CI](https://github.com/patchrail/patchrail/actions/workflows/ci.yml/badge.svg)](https://github.com/patchrail/patchrail/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/pypi/pyversions/patchrail)](https://pypi.org/project/patchrail/)
+
+![patchrail ci explain reading a failed CI log and emitting root cause, confidence, and a reproduce command](docs/assets/ci-explain-demo.gif)
+
+The recording above is real output from the bundled
+`examples/ci-triage/typescript-import-type-drift.log` fixture. No model calls,
+no network, no telemetry: the classifier is a curated rule engine that runs
+entirely on your machine.
+
+## Why maintainers use it
+
+- **40 failure classes** backed by real log signatures — dependency
+  resolution, flaky network, OOM-killed runners, Docker builds, lint,
+  type checks, docs-site builds, and test failures across Python, Node,
+  TypeScript, Go, Rust, Java, .NET, Ruby, PHP, C++, and Swift/Xcode. Run
+  `patchrail ci classes` to list them all (add `--format json` to check
+  coverage from a script).
+- **169 sanitized CI log fixtures** keep the classifier honest: every rule is
+  benchmarked against the public fixture zoo in `examples/ci-triage/` on every
+  test run.
+- **23 secret-redaction patterns** (GitHub/GitLab/npm/PyPI/AWS tokens, private
+  keys, JWTs, emails, home paths) so logs can be shared safely.
+- **Local-first by design**: no network access, no billing, no external model,
+  no telemetry. Nothing leaves the machine.
+- **Markdown for humans, JSON for automation** — pipe the same result into a
+  PR comment or a workflow step.
+
+## Quickstart
+
+PatchRail is published on PyPI:
+
+```bash
+pipx install patchrail
+```
+
+Classify any failed CI log:
+
+```bash
+patchrail ci explain --log failed-ci.log
+```
+
+Or try it on a bundled fixture from a clone of this repo:
+
+```bash
+git clone https://github.com/patchrail/patchrail
+cd patchrail
+patchrail ci explain --log examples/ci-triage/dependency-failure.log --format markdown
+```
+
+Real output:
+
+```markdown
+# PatchRail CI Report
+
+- Root cause: `python_dependency_resolution`
+- Confidence: `0.89`
+- Subsystem: Python dependency installation
+- Reproduce: `python -m pip install -r requirements.txt`
+- Suggested action: Pin or relax the conflicting dependency range, then rerun the same install command and the affected tests.
+
+## Evidence signals
+
+- `Could not find a version that satisfies the requirement`
+- `Cannot install .*because these package versions have conflicting dependencies`
+- `ResolutionImpossible`
+```
+
+It also reads from stdin, so you can pipe a log straight in:
+
+```bash
+tail -n 200 failed-ci.log | patchrail ci explain
+```
+
+Every failure class has a step-by-step remediation write-up in
+[docs/fix/](docs/fix/README.md).
+
+## GitHub Action
+
+Run the same triage on every red CI run with
+[`patchrail/ci-triage-action`](https://github.com/patchrail/ci-triage-action)
+(also on the
+[GitHub Marketplace](https://github.com/marketplace/actions/patchrail-ci-triage)).
+It classifies the log locally on the runner — no PR, no comment, nothing
+leaves the job:
+
+```yaml
+- name: PatchRail CI triage
+  if: failure()
+  uses: patchrail/ci-triage-action@v1
+  with:
+    log-path: test.log
+```
+
+The `@v1` drop-in exposes `failure-class`, `confidence`, and `guide-url`, plus a
+run annotation and job summary. See
+[docs/using-the-action.md](docs/using-the-action.md) for its full inputs and
+outputs, or [examples/ci-triage-action](examples/ci-triage-action/README.md) for
+the artifact shapes of both `@v1` and the richer in-repo composite.
+
+## Features
+
+| Feature | Status | Notes |
+| --- | --- | --- |
+| CI failure triage (`ci explain`, `ci classify`, `ci classes`) | Beta | 40 failure classes for GitHub Actions-style logs and common toolchains |
+| Secret redaction (`redact`, `ci explain --redact`) | Beta | 23 patterns for tokens, keys, emails, and home paths |
+| Reports | Beta | Markdown, JSON, and plain text |
+| Fixture benchmark (`ci benchmark`) | Beta | Scores the classifier against all 153 public fixtures |
+| GitHub Action | Beta | Read-only triage artifact on failed workflows |
+| Local queue / control plane (`queue`) | Experimental | SQLite-backed work items with human approval states |
+| Funded issue discovery (`funded-issues`) | Experimental (read-only) | Safe-only defaults, no claiming or commenting; see [docs/funded-issues-ethics.md](docs/funded-issues-ethics.md) |
+
+## Local-first & safety
+
+PatchRail never phones home. The classifier needs no API key, no GitHub App,
+no repo write permission, and no external model call. Write actions (PRs,
+comments, claims) are out of scope; anything that could become one sits behind
+an explicit human approval state.
+
+Secret redaction is a first-class feature, not an afterthought. Redact a log
+before sharing it anywhere:
+
+```bash
+patchrail redact --log failed.log > failed.redacted.log
+patchrail ci explain --redact --log failed.log
+```
+
+The redaction pass covers GitHub, GitLab, npm, PyPI, AWS, Stripe, Slack,
+Google, Hugging Face, and SendGrid credentials, private key blocks, JWTs,
+bearer tokens, URL-embedded credentials, `*_TOKEN`/`*_SECRET` environment
+assignments, email addresses, and user home paths.
+
+See [ETHICS.md](ETHICS.md), [SECURITY.md](SECURITY.md), and
+[docs/threat-model.md](docs/threat-model.md).
+
+## Roadmap
+
+- **v0.3** — public demo of the local agent control plane: SQLite-backed work
+  queue, approval gates, and audit export.
+- **v0.4** — ethical funded-maintenance workflow: read-only discovery with
+  human-gated follow-up, no automated claiming.
+
+Details in [docs/roadmap.md](docs/roadmap.md).
+
+## Documentation
+
+- [Quickstart](docs/quickstart.md)
+- [jq cookbook for the JSON classifier output](docs/json-cookbook.md)
+- [Fix guides per failure class](docs/fix/README.md)
+- [CI Failure Zoo](docs/ci-failure-zoo.md)
+- [GitHub Actions CI triage](docs/github-action.md)
+- [Using the action in your own repository](docs/using-the-action.md)
+- [Agent Control Plane](docs/agent-control-plane.md)
+- [API reference](docs/api-reference.md)
+- [Threat model](docs/threat-model.md)
+- [Funded issue ethics](docs/funded-issues-ethics.md)
+
+## Contributing
+
+The fastest way in is **adding a CI fixture — it takes about 10 minutes**:
+grab a failed log, redact it, trim it to the smallest excerpt that still shows
+the root cause, and add it with its expected classification under
+`examples/ci-triage/`. The full path is in
+[CONTRIBUTING.md](CONTRIBUTING.md), and the
+[CI failure fixture issue template](.github/ISSUE_TEMPLATE/ci_failure_fixture.md)
+works if you are not ready to open a pull request.
+
+Issues labeled
+[`good first issue`](https://github.com/patchrail/patchrail/labels/good%20first%20issue)
+are scoped for first-time contributors.
+
+Run the checks locally before opening a PR:
+
+```bash
+uv run --extra dev pytest -q
+uv run --extra dev ruff check .
+uv run --extra dev patchrail ci benchmark examples/ci-triage --format json
+```
+
+## License
+
+Apache-2.0.

patchrail-0.3.0/README.md

@@ -0,0 +1,190 @@
+# PatchRail
+
+Local-first CI failure triage for open-source maintainers. Paste a failing CI
+log, get the failure class, the reproduction command, and a suggested fix
+strategy — in seconds, fully offline.
+
+[![PyPI](https://img.shields.io/pypi/v/patchrail)](https://pypi.org/project/patchrail/)
+[![CI](https://github.com/patchrail/patchrail/actions/workflows/ci.yml/badge.svg)](https://github.com/patchrail/patchrail/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/pypi/pyversions/patchrail)](https://pypi.org/project/patchrail/)
+
+![patchrail ci explain reading a failed CI log and emitting root cause, confidence, and a reproduce command](docs/assets/ci-explain-demo.gif)
+
+The recording above is real output from the bundled
+`examples/ci-triage/typescript-import-type-drift.log` fixture. No model calls,
+no network, no telemetry: the classifier is a curated rule engine that runs
+entirely on your machine.
+
+## Why maintainers use it
+
+- **40 failure classes** backed by real log signatures — dependency
+  resolution, flaky network, OOM-killed runners, Docker builds, lint,
+  type checks, docs-site builds, and test failures across Python, Node,
+  TypeScript, Go, Rust, Java, .NET, Ruby, PHP, C++, and Swift/Xcode. Run
+  `patchrail ci classes` to list them all (add `--format json` to check
+  coverage from a script).
+- **169 sanitized CI log fixtures** keep the classifier honest: every rule is
+  benchmarked against the public fixture zoo in `examples/ci-triage/` on every
+  test run.
+- **23 secret-redaction patterns** (GitHub/GitLab/npm/PyPI/AWS tokens, private
+  keys, JWTs, emails, home paths) so logs can be shared safely.
+- **Local-first by design**: no network access, no billing, no external model,
+  no telemetry. Nothing leaves the machine.
+- **Markdown for humans, JSON for automation** — pipe the same result into a
+  PR comment or a workflow step.
+
+## Quickstart
+
+PatchRail is published on PyPI:
+
+```bash
+pipx install patchrail
+```
+
+Classify any failed CI log:
+
+```bash
+patchrail ci explain --log failed-ci.log
+```
+
+Or try it on a bundled fixture from a clone of this repo:
+
+```bash
+git clone https://github.com/patchrail/patchrail
+cd patchrail
+patchrail ci explain --log examples/ci-triage/dependency-failure.log --format markdown
+```
+
+Real output:
+
+```markdown
+# PatchRail CI Report
+
+- Root cause: `python_dependency_resolution`
+- Confidence: `0.89`
+- Subsystem: Python dependency installation
+- Reproduce: `python -m pip install -r requirements.txt`
+- Suggested action: Pin or relax the conflicting dependency range, then rerun the same install command and the affected tests.
+
+## Evidence signals
+
+- `Could not find a version that satisfies the requirement`
+- `Cannot install .*because these package versions have conflicting dependencies`
+- `ResolutionImpossible`
+```
+
+It also reads from stdin, so you can pipe a log straight in:
+
+```bash
+tail -n 200 failed-ci.log | patchrail ci explain
+```
+
+Every failure class has a step-by-step remediation write-up in
+[docs/fix/](docs/fix/README.md).
+
+## GitHub Action
+
+Run the same triage on every red CI run with
+[`patchrail/ci-triage-action`](https://github.com/patchrail/ci-triage-action)
+(also on the
+[GitHub Marketplace](https://github.com/marketplace/actions/patchrail-ci-triage)).
+It classifies the log locally on the runner — no PR, no comment, nothing
+leaves the job:
+
+```yaml
+- name: PatchRail CI triage
+  if: failure()
+  uses: patchrail/ci-triage-action@v1
+  with:
+    log-path: test.log
+```
+
+The `@v1` drop-in exposes `failure-class`, `confidence`, and `guide-url`, plus a
+run annotation and job summary. See
+[docs/using-the-action.md](docs/using-the-action.md) for its full inputs and
+outputs, or [examples/ci-triage-action](examples/ci-triage-action/README.md) for
+the artifact shapes of both `@v1` and the richer in-repo composite.
+
+## Features
+
+| Feature | Status | Notes |
+| --- | --- | --- |
+| CI failure triage (`ci explain`, `ci classify`, `ci classes`) | Beta | 40 failure classes for GitHub Actions-style logs and common toolchains |
+| Secret redaction (`redact`, `ci explain --redact`) | Beta | 23 patterns for tokens, keys, emails, and home paths |
+| Reports | Beta | Markdown, JSON, and plain text |
+| Fixture benchmark (`ci benchmark`) | Beta | Scores the classifier against all 153 public fixtures |
+| GitHub Action | Beta | Read-only triage artifact on failed workflows |
+| Local queue / control plane (`queue`) | Experimental | SQLite-backed work items with human approval states |
+| Funded issue discovery (`funded-issues`) | Experimental (read-only) | Safe-only defaults, no claiming or commenting; see [docs/funded-issues-ethics.md](docs/funded-issues-ethics.md) |
+
+## Local-first & safety
+
+PatchRail never phones home. The classifier needs no API key, no GitHub App,
+no repo write permission, and no external model call. Write actions (PRs,
+comments, claims) are out of scope; anything that could become one sits behind
+an explicit human approval state.
+
+Secret redaction is a first-class feature, not an afterthought. Redact a log
+before sharing it anywhere:
+
+```bash
+patchrail redact --log failed.log > failed.redacted.log
+patchrail ci explain --redact --log failed.log
+```
+
+The redaction pass covers GitHub, GitLab, npm, PyPI, AWS, Stripe, Slack,
+Google, Hugging Face, and SendGrid credentials, private key blocks, JWTs,
+bearer tokens, URL-embedded credentials, `*_TOKEN`/`*_SECRET` environment
+assignments, email addresses, and user home paths.
+
+See [ETHICS.md](ETHICS.md), [SECURITY.md](SECURITY.md), and
+[docs/threat-model.md](docs/threat-model.md).
+
+## Roadmap
+
+- **v0.3** — public demo of the local agent control plane: SQLite-backed work
+  queue, approval gates, and audit export.
+- **v0.4** — ethical funded-maintenance workflow: read-only discovery with
+  human-gated follow-up, no automated claiming.
+
+Details in [docs/roadmap.md](docs/roadmap.md).
+
+## Documentation
+
+- [Quickstart](docs/quickstart.md)
+- [jq cookbook for the JSON classifier output](docs/json-cookbook.md)
+- [Fix guides per failure class](docs/fix/README.md)
+- [CI Failure Zoo](docs/ci-failure-zoo.md)
+- [GitHub Actions CI triage](docs/github-action.md)
+- [Using the action in your own repository](docs/using-the-action.md)
+- [Agent Control Plane](docs/agent-control-plane.md)
+- [API reference](docs/api-reference.md)
+- [Threat model](docs/threat-model.md)
+- [Funded issue ethics](docs/funded-issues-ethics.md)
+
+## Contributing
+
+The fastest way in is **adding a CI fixture — it takes about 10 minutes**:
+grab a failed log, redact it, trim it to the smallest excerpt that still shows
+the root cause, and add it with its expected classification under
+`examples/ci-triage/`. The full path is in
+[CONTRIBUTING.md](CONTRIBUTING.md), and the
+[CI failure fixture issue template](.github/ISSUE_TEMPLATE/ci_failure_fixture.md)
+works if you are not ready to open a pull request.
+
+Issues labeled
+[`good first issue`](https://github.com/patchrail/patchrail/labels/good%20first%20issue)
+are scoped for first-time contributors.
+
+Run the checks locally before opening a PR:
+
+```bash
+uv run --extra dev pytest -q
+uv run --extra dev ruff check .
+uv run --extra dev patchrail ci benchmark examples/ci-triage --format json
+```
+
+## License
+
+Apache-2.0.